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This is a book about what we believe may well be the computer pro¬ 
gramming language of the ’90s: Smalltalk. No, you’re not about to be 
subjected to yet another sales pitch for Object-Oriented Programming 
(OOP) and the languages that support that approach to software design 
and construction. If you’ve purchased this book, you’re already sold on 
OOP and probably at least to some degree on Smalltalk as well. 

As we looked at the available book titles about Smalltalk program¬ 
ming when we started the original version of this project, we noticed 
that those books, as well as documentation for Smalltalk products, pro¬ 
vided very good introductory information. But the level of detail was 
such that these materials did not really help the reader to see easily how 
real-world applications could be constructed in Smalltalk. Yet we real¬ 
ized, too, that once you have a Smalltalk environment in your hands, the 
natural thing to do is build something useful and interesting. Helping 
you understand how to build applications is the sole focus of this book. 

Who Should Read This Bilk? 

This book is specifically aimed at people who are interested in learning 
to build real-world applications using IBM Smalltalk. We assume that 
you are already sold on OOP and IBM Smalltalk and that you are famil¬ 
iar with basic programming concepts contained in the IBM Smalltalk 
tutorial. We do not assume that you are a professional programmer. 

You will benefit most from this book if you work through the projects 
it contains. But Smalltalk code tends to be quite readable; if you don’t 
have ready access to a system running IBM Smalltalk, you can still gain 
some insights into the design, coding techniques, and strategies that will 
make you a better Smalltalk programmer. 
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What Should Yei Expect to Learn? 

Obviously, we expect you to make a reasonably serious time commit¬ 
ment to learning OOP and IBM Smalltalk. Why should you do this? What’s 
in it for you? 

In brief, we expect that by the time you finish this book, you will learn 
how to handle the following programming-related tasks in IBM Smalltalk: 


m how to organize your classes into hierarchies that make them 
easier to reuse and extend 

h where and how to find reusable classes in the IBM Smalltalk class 
library 

m how to design and implement projects related to all of the key 
concepts in IBM Smalltalk, including simulations 

You will do all of this by following through the book from start to 
finish as we take you through the process of learning the IBM Smalltalk 
environment, tools, libraries, and techniques on a practical level. 

What Does This Book Lover? 

The primary focus of this book is on IBM Smalltalk for Windows and OS/ 
2. This book is divided into 17 chapters, some of which may be longer 
than you are used to seeing in computer books. With the exception of 
Chapter 1, it follows a careful organization of background and theory 
followed by a specific project for you to build that reinforces and ex¬ 
tends the concepts in the preceding chapter. 

Chapter 1 is a brief look at the IBM Smalltalk environment. It encom¬ 
passes an overview of the IBM Smalltalk tools, some emphasis on 
browsers, an introduction to the use of the Debugger, and a dis¬ 
cussion of how to customize the IBM Smalltalk environment to 
make it more compatible with your style of programming and de¬ 
sign. Some of the material in this chapter reviews information 
found in the IBM tutorial, and some of it is new material. 

Chapter 2 focuses on the Smalltalk language itself. The language is, 
of course, just one of the tools in the IBM Smalltalk environment. 
This chapter looks at basic IBM Smalltalk syntax, outlines some of 
the important classes in the IBM Smalltalk class library that we’ll 
be dealing with in this book, and points out some key program¬ 
ming concepts that are either glossed over or not covered in detail 
in the IBM manuals. 



INTRODUCTION 

xxi 


Chapter 3 puts the material in the first two chapters to work in the 
first of seven projects around which the book is centered. In this 
chapter, you’ll build a small project that extends the IBM Smalltalk 
environment by adding a simple but useful application to the sys¬ 
tem. This application is called the Prioritizer; it helps you to r ank 
and sort through a list of choices you enter. You’ll see how to de¬ 
sign this application and become comfortable with the idea of 
modifying the IBM Smalltalk environment. Many programmers 
coming to Smalltalk from other languages and approaches find a 
difficult psychological barrier in the fact that all of the program¬ 
ming you do in Smalltalk entails changing the environment itself. 
This chapter will help you over that hurdle and build a useful 
application in the process. 

Chapter 4 turns our attention to the development processes involved in 
designing' and creating IBM Smalltalk applications. As you’ll see, pro¬ 
gramming in Smalltalk is a little like peeling an onion. There are 
several approaches to programming, none of which is the best and 
all of which may actually be used in creating a single application. 

Chapter 5 will then demonstrate the simplest approach to program¬ 
ming in IBM Smalltalk as you build a small counter project. While 
simplistic in execution, this project requires that you understand 
the basic use of the tools that are at the core of all IBM Smalltalk 
interactive applications. It also teaches you the rudiments of cre¬ 
ating the user interface portion of a IBM Smalltalk application. 

Chapter 6 discusses the use of system Ul-related classes and methods 
and the all-important concept of events in IBM Smalltalk. You’ll 
learn the key classes and methods that you need to understand 
deeply to be able to write efficient and effective IBM Smalltalk 
code. You’ll also learn how events are trapped, handled, and dis¬ 
patched in IBM Smalltalk. 

Chapter 7 puts the concepts introduced in Chapter 6 to work by guid¬ 
ing you through the construction of a calendaring application. This 
program, which we build on in all subsequent chapters, displays 
a calendar for any month and year you wish and highlights holi¬ 
days and the current date in color. 

Chapter 8 describes how to create and manage IBM Smalltalk appli¬ 
cations that use more than one window. The chapter begins with 
a discussion of how and why disparate objects that share a space 
can communicate with one another. The two techniques by which 
these objects can communicate are called message broadcasting 
and moderation and are detailed in the chapter. 
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Chapter 9 builds on the calendaring application of Chapter 7 and pro¬ 
vides an example of the use of the Application Controller archi¬ 
tecture of Chapter 7 by adding an appointment book capability to 
the calendaring application. This rudimentary but useful addition 
permits you to schedule activities and have those activities dis¬ 
played in a second window when you choose a date in the calen¬ 
dar view. The application demonstrates the management of mul¬ 
tiple views in a single application. 

Chapter 10 turns our attention to the graphic world of IBM Smalltalk. 
This language lives in an inherently graphic environment. In this 
chapter, we’ll look at the basic graphic concepts: forms, drawing 
primitives, and animation. Along the way we’ll take a brief look at 
some of the mathematics involved in all graphic work. 

Chapter 11 puts some of these basic graphic techniques to work as 
you build your fifth IBM Smalltalk project, a busyness indicator 
window for your growing application. You’ll see the incremental 
development approach and understand how the graphic aspects 
of the program are used both to create the interface for the user 
and to generate the display of data. 

Chapter 12 does for the text world of IBM Smalltalk what Chapter 10 
did for the graphic world. It explores IBM Smalltalk’s text editing 
concepts and how they are used. It includes a fairly complete dis¬ 
cussion of the support for multiple fonts included for the first time 
in IBM Smalltalk. 

Chapter 13 gives you a chance to try out your knowledge of the tex¬ 
tual aspects of the language and environment by adding styled 
labels to the busyness indicator. 

Chapter 14 introduces the IBM Common File System and its sub¬ 
systems. As you are introduced to these subsystems you will learn 
about the management of external files in IBM Smalltalk, discuss¬ 
ing along the way the primary classes and methods you will need 
to create, open, close, update, and manipulate file contents from 
within your application. 

Chapter 15 utilizes the information presented in Chapter 14 to ex¬ 
tend the AppointmentBook application. You will add external 
data storage and retrieval by extending two classes, and add 
save and retrieve menu items to the AppointmentBookWindow 
Appointment menu. 

Chapter 16 focuses on the relatively advanced concept of multipro¬ 
cessing. IBM Smalltalk enables you to build applications that use 
multiple execution threads, a notion that is difficult or impossible 
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to implement in Microsoft Windows with other tools but one which 
is becoming increasingly important in modern-day applications. 
This feature is particularly important when creating software for 
IBM’s OS/2 2.1 or later. 

Chapter 17 concludes the main extensions to the calendaring appli¬ 
cation begun in Chapter 7 by adding an alarm clock, complete 
with chime sounds, to it. You’ll learn how to start and stop mul¬ 
tiple processes and how to integrate a multiprocessing design into 
an application. 

What’s oi the Disk? 

This book comes with a disk that contains all of the complete program 
examples in this book, already typed in for you. If you’re not the kind of 
person who learns more about programming by typing in code, you’ll 
find this disk a real time-saver! 

The files on the disk are arranged into subdirectories by chapter. Each 
subdirectory includes a fde in IBM Smalltalk fileln format. Just follow 
the instructions on the disk label or in the README.TXT file on the disk 
to add this code to your Smalltalk image. 

What This Book Is lot 

This book does not attempt to do any of the following: 

■ Persuade you that OOP is important, efficient, effective, or indis¬ 
pensable. We believe it is all of these things, but other writers 
have been touting this technology for a long time and many of 
them are better at such writing than we are. 

■ Teach you basic OOP concepts. You should understand classes, 
methods, inheritance, encapsulation, polymorphism, and other key 
OOP ideas, at least minimally, before you attempt to read this book. 
If you don’t, then the IBM documentation provides some excellent 
background in the subject. There are numerous other books dedi¬ 
cated to teaching OOP. 

■ Compare OOP or Smalltalk to other programming methodologies, 
except incidentally as the occasion seems appropriate. If you are 
an experienced programmer, you can draw your own analogies 
as you progress through the book. 
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Sue Rotational Conventions Used in This Book 

As with any programming book, this one adopts certain notational and 
syntactic conventions to make readability easier. Here are the most im¬ 
portant of those conventions: 

a All class names are printed in bold type except in section head¬ 
ings, which are already bold, and where they are usually evidently 
class names from their context. 

m All method names are printed in italic type, including in section 
headings. 

m We use Courier font to reproduce program listings. It looks like this: 

sample code 

m We try to differentiate between elements of the Smalltalk language 
and environment that are peculiar to IBM Smalltalk and those 
that are more generic and could be considered applicable regard¬ 
less of the dialect of the language you choose. We use the term 
IBM Smalltalk to mean that the subject being discussed is either 
unique to IBM Smalltalk or implemented differently than in other 
versions of the language. When a function or activity is applicable 
only to the Windows version of IBM Smalltalk, we use the full 
name of that product, IBM Smalltalk. Where we use the term 
Smalltalk, we refer to the broader context of the language of which 
IBM Smalltalk is but one implementation. 



CHAPTER 
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In this chapter we look at the various tools that make up the IBM Smalltalk 
programming environment. We examine browsers, inspectors, 
workspaces, and the Debugger. We include some tips to help you use 
IBM Smalltalk programming tools more effectively. 

The documentation that comes with IBM Smalltalk explains these tools 
in some detail. We won’t duplicate that information here. We will do two 
things for each tool: provide a condensed overview of its use and give 
tips and hints about it that either don’t appear in the documentation or 
are difficult to ferret out. 

in Overview of the Environment 

Any productive object-oriented development environment consists of 
three interrelated elements: 


■ Tools that facilitate use of the language (editors, browsers, debuggers, 
and the like) 

m The language itself (the compiler) 

m The class libraries that give the programmer access to the operating 
system, user interface, and other elements of program design 


This chapter focuses on tools. Chapter 2 reviews and provides insights 
into the IBM Smalltalk language. The rest of the book introduces various 
features of IBM Smalltalk by helping you construct some applications 
using these tools and the language in conjunction with the most impor¬ 
tant and useful classes in the class library. 

The IBM Smalltalk environment is complex to describe because IBM 
has seen fit to give you, the programmer, a tremendous amount of flex¬ 
ibility with respect to the operation of many elements of the environ¬ 
ment. Where most other dialects of the Smalltalk language supply a pow¬ 
erful set of tools, IBM Smalltalk extends that notion by allowing you to 
select, configure, define, and personalize your environment. 
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For the most part, we’ll stick with describing IBM Smalltalk as it comes 
out of the box. But since we are Smalltalk programmers as well as writ¬ 
ers, we have a tendency to find certain ways of working that inevitably 
color the way we do our work and, ultimately, how we write about that 
process. We’ll let you know when we’re describing something either that 
isn’t part of the normal installation of IBM Smalltalk or that we have 
customized somehow. 

The problem of user customization in the IBM Smalltalk development 
environment is complicated by the fact that there are almost always two 
or more ways to accomplish any task. For example, if we tell you to set 
up a particular scrolling list in a browser to look at a certain kind of 
object or program element, you may be able to do this task from two 
different menus or with a Control-key equivalent. As a rule, we’ll tell 
you what to do and mention our accustomed way of doing it, but be 
aware that this way is part of our Smalltalk programming style and that 
you’ll undoubtedly develop your own style over time. 

With the caveats out of the way, let’s get to work. Most of the tools 
you’ll find useful in the IBM Smalltalk environment are windows. All 
windows have certain things in common, including: 


m A title bar containing the title of the window and providing a handle 
for direct manipulation of the window 
h One or more subpanes (partitions) of various types 
m Pop-up menus associated with most panes 

■ Standard platform controls that permit such operations as closing, 
collapsing, zooming, and resizing the window 


Some windows also include buttons you can click with the mouse to 
change the state of things in them. For example, the TrailBlazing 
Browser (TrailBlazer for short) has two buttons in one of its lists 
labeled “Public” and “Private” that let you select which type or types 
of methods you wish displayed. 

Your IBM Smalltalk environment automatically includes the System 
Transcript window when you launch the system. This window can be 
minimized, maximized, resized, and moved. It can also be closed, but 
closing it will also exit IBM Smalltalk. 
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Choosing a Browser 

One of the first things you’ll want to do after installing IBM Smalltalk is 
to decide whether you want to work in a collection of standard Smalltalk 
browsers or in a specially designed universal browser called TrailBlazer 
(or the “TrailBlazing Browser”). 

The standard IBM Smalltalk browser appears in Figure 1-1. The figure 
shows a browser being used to browse the class library, but a similar win¬ 
dow will open if you want to browse the classes in an appbcation or some 
subset of a class library (for instance, a particular class). 

As you can see, this standard browser has four small subpanes across 
the top of its window. The contents of these lists depends on three things: 
what you are browsing (applications or classes), what’s selected in each 
list, and which buttons are pressed beneath the three panes that have 
buttons associa ted with them. If you are browsing applications, the lists 
contain, from left to right, applications in the image, classes associated 
with each application as you select them, categories of methods in each 
class as you select them, and names of methods, respectively. If you are 
browsing classes, the first two lists are reversed, but the remaining lists 
stay the same. 
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Figure 1-1. 


The standard browser in IBM Smalltalk 
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The large pane at the bottom of the standard browser shows either 
the source of a selected method (or the definition of a class if a class is 
selected) or a comment for a particular class or method, depending on 
what’s selected in the top lists and the state of the button in the lower- 
right corner of the browser. 

Clearly you can get a lot of information out of a standard IBM Smalltalk 
browser. (And we haven’t even explored the menus yet!) So why would 
anyone want to create an even more powerful browser? The answer lies 
in the one word that describes the key difference between the two types 
of browsers: flexibility. 

Whereas the standard browser offers a fixed view of the Smalltalk 
world, a TrailBlazer allows you to decide what information you want to 
see in each list, how many lists will be available to you in a single browser, 
and the order of the lists. You can set up a TrailBlazer to mimic the 
layout and behavior of a standard browser by defining each list to dis¬ 
play the appropriate information: applications, classes, categories, and 
methods. But you can also decide, not entirely arbitrarily but with a 
reasonable amount of latitude, how you’d like to look at a particular 
portion (or all) of a class library. 

Figure 1-2 shows a TrailBlazer set up so that we are looking at classes 
and instance methods only. Notice that the third list is labeled “Trail 
End.” This is TrailBlazer’s way of indicating when there is no further 
useful information in the next pane to the right or that the right list 
doesn’t exist (as in this case). 

Notice that the thin lines under the top lists have changed. There are 
now four lines (called “piano keys”); note that the leftmost is hollow, 
while the other three are filled. This rather ingenious trick allows you to 
navigate among numerous lists in the upper portion of a TrailBlazer 
browser while focusing on only three panes at a time. 
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Figure 1-2. 


A TrailBlazer browser with minimal information 


Figure 1-3 shows the same TrailBlazer, with a third list added, show¬ 
ing all implementers of the messageString: method in the image. 
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A TrailBlazer browser with a third list added 

In Figure 1-4, we’ve added a fourth pane, showing the instance 
variables used in a method we chose in the “All Implementers” list. 
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Figure 1-4. 


A fourth list added to the TrailBlazer browser 


One significant advantage of the TrailBlazer Browser is that, as you 
navigate through the information in your Smalltalk environment, you 
can stay within a single window. With the standard browser, a new win¬ 
dow is opened for almost every navigation or query. 

You will, of course, make your own choice of which browser type to 
use. You make the choice from the Smalltalk Tools menu in the System 
Transcript window. There are two mutually exclusive options: Use Stan¬ 
dard Browsers and Use Enhanced Browsers. The currently selected op¬ 
tion is gray and checked. If you have one or more browsers of one type 
open when you choose the other alternative, the new choice applies only 
to browsers you open subsequently. (But we don’t recommend having 
browsers of both styles open at once; it’s very confusing!) 

Despite our familiarity with the standard browser approach, we quickly 
found ourselves using the TrailBlazer browser. The flexibility proves to 
be helpful in many situations, and the more Smalltalk coding you do, the 
more you will come to appreciate that flexibility. In this book, we’ll use 
the TrailBlazer browser, so we recommend that you do so as well, at 
least while you work through the projects in this book. 



As you will see in detail in Chapter 2, IBM Smalltalk tends to look at the Smalltalk 
image with which you work as divided first into applications and then into classes, 
at least from the viewpoint of the tools you use. Indeed, some things cannot be done 
with a class; they must be done to the application. (For example, as well see later in 
this chapter, to delete the last remaining class of an application, the application 
class, you must delete the application itself.) 


Using the TrailBlazer Browser 

Most experienced Smalltalk programmers maintain at least one acces¬ 
sible class browser in their environment. This window is used so often 
that we’re going to refer to it simply as “the browser,” even though there 
are many browsers in the environment. When we mean a browser other 
than a TrailBlazer that is opened on either applications or classes (and 
we’ll specify which only when it’s essential to your understanding), we’ll 
describe the browser more specifically. 

You open a new browser by choosing Browse Applications or Browse 
Classes from the Smalltalk Tools menu in the System Transcript. When 
you do, the browser opens with no class or application selected. Only the 
leftmost list has anything in it. By default, the browser contains three 
lists: applications, classes, and instance categories if you are browsing 
applications; classes, instance categories, and instance methods if you 
are browsing classes. 


You can customize the TrailBlazers default behavior so that when you open a 
TrailBlazer browser on classes, for example, it will show you classes, instance 
methods (without categorization), and instance variables. The combinations, while 
not endless, are certainly numerous. See the TrailBlazer documentation provided 
with IBM Smalltalk for instructions in how to customize the TrailBlazer. 



As you select an entry in any of the upper lists, the list to its right is 
updated to reflect the relevant information. In a default class browser, 
for example, when you select a class, the next list to the right will show 
you the categories of instance methods available in that class. Clicking 
on one of the categories results in the next list to the right showing yon 
a list of all the Instance methods in that class that have been defined in 
the selected category. 
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When you select a class, the text editing area at the bottom of the 
browser shows that class’s definition. When you select a method, this 
area shows the source code for that method if it is available (that is, if it 
is not protected from view by IBM or a third party whose classes you 
may be using). 

How do you tell the browser what to place in each list across the top 
of the window? At the top of each list is a drop-down list box that con¬ 
tains all of the options that are logical for this list. You can choose any of 
them, and the browser will automatically update its view. Another thing 
you can do is to click the right mouse button in one of these lists after 
selecting an entry in it. A pop-up menu will then appear with two op¬ 
tions (among others) labeled Show and Open. You can use this pop-up 
menu to select what you’d like the next pane to the right to contain. 



What does "all of the options that are logical" in the preceding paragraph mean? 
Here arises the limitation on complete flexibility at which we have hinted. Because 
the contents of a given list depend on what is selected in the list to its immediate 
left, there has to be some logical connection between adjacent lists. For example, if 
a list contains methods, it makes no sense for the next pane to the right to contain 
another list of instance methods or a list of classes. The TrailBlazer browser handles 
this problem by making only logical choices available to you. 


When working with code from two or more classes simultaneously, you 
can most efficiently set up your environment by opening a separate browser 
for each class with which you are working. (You may wish to use browsers 
open on specific classes, as explained later in this chapter, but the prin¬ 
ciples remain unchanged.) Each time you change the class selected in the 
class list of a browser, you lose the focus on the method you were editing 
before you changed the selection. This process can become inefficient. Since 
IBM Smalltalk permits you to have an unlimited number of browsers open 
at any given time, open as many browsers as you need. 


Templates in the Browser 

When you create a new element of the IBM Smalltalk environment in a 
browser, you are shown a template for that definition in the lower, text¬ 
editing area of the browser. Figure 1-5 shows the template for a new 
method being added to a class. You generate this template by clicking 
the right mouse button in an instance or class methods list pane and 
selecting Template from the pop-up menu. 
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Figure 1-5. 


A template for a new Instance method 


Similarly, if you define a new class, the browser will produce a tem¬ 
plate for you; in this case, however, the template constitutes a definition 
you can simply save, though you may need to edit it before saving it. 

These templates are helpful in reminding you of the content and struc¬ 
ture of a particular type of definition, and for pointing out things like 
comments that your users or other programmers may have a right to 
expect your code to include. 


Removing Classes via the Browser 

As you work with an IBM Smalltalk image (as described in the next sec¬ 
tion), you will occasionally want to “clean it up” by removing classes you 
created for some experimental reason but no longer need. Doing so is 
easy with the browser, with one exception. 

To delete a class from the image, just select it in a browser, click the 
right mouse, and choose the Delete... option from the pop-up menu. After 
asking you to confirm your intention, IBM Smalltalk will delete the class. 


If you accidentally delete a class, don't panic. You can exit from IBM Smalltalk 
without saving the image, and the deleted class will be there when you relaunch 
IBM Smalltalk. If you've made other extensive changes you do want to save, all is 
still not lost. You can save the image under a name other than "image" and then 
recover from the problem (albeit somewhat manually) later. Well have a few tips on 
this process when we discuss "managing your image" later in this chapter. And 
finally, if all else fails, you can browse the Change Log (described in the next 
section) for any changes during the session. 
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Error: 1 63 

Cannot remove the application class from the application. Applications must be removed 
explicitly. 


OK 


Figure 1-6. 


An error resulting from an attempt to delete the application class 


The lone exception to this easy, one-step deletion procedure for classes 
comes if you try to delete the application class (the class of the same 
name as the application). This class is created when you create a new 
application and is inextricably linked with it. If you try to delete such a 
class, IBM Smalltalk will inform you of your error (see Figure 1-6). You 
will have to delete the application to remove the application class. 


The IBM Smalltalk Image 

We have mentioned the notion of a Smalltalk image without really ex¬ 
plaining it. On one level, an image is a simple and basic concept. It is the 
current environment that contains all the compiled methods and instances 
of active objects. 

When you run IBM Smalltalk, you always work with one image at a 
time, particularly for purposes of backup and archival storage of works 
in process. 

As you work in IBM Smalltalk, the environment is keeping careful track 
of everything you do in a special file called CHANGES.LOG. This file is 
referred to as the Change Log and has been the salvation of more than 
one Smalltalk programmer who got into trouble (through no fault of his 
or her own, of course). All dialects of Smalltalk include a Change Log in 
one form or another, but IBM Smalltalk goes one step further by offering 
a built-in browser for this important file. 

Figure 1-7 shows the Change Log Browser, which you activate by se¬ 
lecting System Browse External Code from the Smalltalk Tools menu 
in the System Transcript. 





llHQjjlgJ The: Change Log Browser 


The upper-left list in the Change Log Browser is a means of breaking 
the log entries into manageable chunks of 200 or fewer changes at a 
time. Descriptions of the changes appear as one-line entries in the right- 
hand list. Clicking on an entry in this list reveals, in the large editing 
pane at the bottom of the window, the contents of that change, if any. 
(We say “if any” because some kinds of changes, particularly those pre¬ 
ceded by “Do It,” which represent actions taken in the image rather 
than modifications to the image, don’t have any “source code” associ¬ 
ated with them.) 

As you can see in Figure 1-7, the Change Log tracks the actions you 
take that affect the image; in this case, we’ve defined a new class. You 
may, in the course of developing an application, redefine a class several 
times. All of those definitions appear in the Change Log, which keeps 
track of the changes in chronological order so that it always uses the 
most current definition when you ask for it. 

The Change Log Browser is quite powerful. With it, you can restrict 
your view to a certain class or selector (another name for a message), 
remove “clutter” (such as what will undoubtedly become a huge accu¬ 
mulation of “Do It” entries), and search for specific entries. 
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Question 


The image will be saved after successfully compressing changes. 
All external code browsers will be reset if this process is continued. 

Do you still wish to compress changes? 


Yes 

mad 


m - 


Figure 1-8. 


I The dialog warning of consequences of "Compress Changes..." 


As you can imagine, the Change Log can become quite large very 
quickly during intense application development. Periodically, you’ll want 
to reduce its size. To do so, simply choose System Compress Changes 
from the Smalltalk Tools menu in the System Transcript. When you in¬ 
voke this command, IBM Smalltalk reminds you of the consequences of 
this relatively drastic action (see Figure 1-8) before proceeding. 

When you choose to compress changes, IBM Smalltalk clears the con¬ 
tents of the Change Log except for the latest copy of each new or changed 
method. It also removes class definitions and automatically saves a new 
image file. 

You can save even more disk space and increase efficiency in your 
IBM Smalltalk image by choosing System >■ Compress Sources from the 
Smalltalk Tools menu. This option creates an entirely new source code 
file for each method; it then empties the Change Log and automatically 
saves a new image file. The result, then, is an entirely new base system 
with which to work. 


Using the Other Browsers 

You may find occasional use for two other types of browsers in IBM 
Smalltalk. They are most useful when you are “playing detective” and 
trying to find a particular class or method in the class library. 

The first of these two types, a class browser, lets you browse a par¬ 
ticular class just as you would in a class hierarchy browser, without the 
noise of the rest of the library. You can think of it as a focused browser. 
There are several ways to invoke a class browser, the most common of 
which are these: 
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» From the Smalltalk Tools menu in the System Transcript, select 
Browse Class. 

■ Select a class in any browser and right-click on it, then select Open >- 
Hierarchy from the pop-up menu. 


The second useful type of browser is the method browser. You can 
invoke this browser from the Smalltalk Tools menu by choosing Browse 
Senders or Browse Implementers and then supplying the name of the 
method you wish to explore. Figure 1-9 shows such a browser as it would 
appear if you were using standard IBM Smalltalk browsers. If you are 
using the Trad Blazer browser, this browser looks identical to the others, 
of course (the whole point of the TrailBlazer being to create a single, 
universal browser design for all purposes). 

When you 1: ave opened a method browser, you can click on any indi¬ 
vidual entry and see, in the bottom editing pane, the source code for the 
method that sends the message which you are browsing. The first occur¬ 
rence of the message you are examining is highlighted in the source 
code listing. 


File Edit Methods 


Senders of #isString 


i 


AbtCPointerField>>put:into:parentOffset: 
AbtD e b u g g e r> > co e rceT o Stri n g: 
AbtDebugger>>imageBuildlDString 
AbtFileSpec>>spec: 


AbtMRIGrou 


AbtMRIGrou pH e a der>>category: 


openOn: anAbtFileSpecOrString 

"Open the receiver on anAbtFileSpecOrString. Answer true 
if successful false otherwise." 

self fileSpec: (anAbtFileSpecOrString 

ifTrue:[ AbtFileSpec fsleSpec: anAbtFileSpecOrString ] 


m - ■ - - - 4 Lir:i _ o-_m 

[*j 

-j 

jjfrom AbthJLSSubApp 

1 source 

j 


A method browser using standard browsers 
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Using Inspectors 

Next to the browsers, inspectors are the most useful tools in IBM 
Smalltalk. Inspectors are primarily useful during debugging, but they 
can be helpful at other times as well. 

A browser, as we’ve seen, allows you to look at a class or method. An 
inspector lets you examine the contents of objects and of the instance 
variables (which are, in turn, objects, since everything in Smalltalk is an 
object) of a particular object. 

An inspector also lets you change the contents of an object and to 
save those options on the fly. 

There are, as you’ve come to expect by now, several ways of opening 
an inspector. The most common are these: 

■ Send an inspect message to the object, class, or application you wish 
to examine by typing its name followed by “inspect” in a Workspace 
or the System Transcript, then selecting and executing the line. 

m Select the class or application you wish to inspect in a browser and 
then choose Inspect from the Edit menu. 

Note that you cannot inspect an object (that is, an instance of a class 
created by a running application) unless the program that creates it is 
running. You must halt program execution (with a halt message in your 
code or by pressing (cntriXBreaiT ) while the program is running but after 
the object in which you are interested has been created). 

Figure 1-10 shows an inspector at work. We opened this inspector by 
pressing (crniT )- (B(iiir ), then choosing Inspect from the Inspector menu in 
the ensuing debugging window. The left pane of the inspector shows all 
of the instance variables in a particular object (in this case, a UI process, 
but that’s not what’s important here). Clicking on any of these labels 
displays the value of that variable in the right-hand editing pane. 



CHAPTER 1: THE ENVIRONMENT 


15 


IBM Smalltalk Debugger 


File Edit Processes Stack Inspector Value Report 


cess:3794{suspended,3} self 


-EL.-LU-1- —JO, - 

~ . 1 

Into j 

Oyer J 


DirectedMessage>>#s 

EmSystemConfiquratioi 

C wAp p C o ntext> >#re a d/ 


tempi 

n tpmn? 


j OSWidget 


no source 


OSWidget class Inspector 


File Edit Variables 


specialMethods 

superclass 

methodsArray 

namedlnstVarSize 

instanceShape 

instanceLink 

classLink 

methodDictionary 

subclasses 

instVarNames 

description 

name 

classPool 

sharedPoolNames 


OSWidget 


Figure 1-10. 


The Inspector opened from the Debugger 


You can examine the value of any instance variable using the inspec¬ 
tor. This is often a source of insight as you debug programs because one 
of the most common sources of IBM Smalltalk programming errors is 
failing to assign a correct or appropriate value to an instance variable. 


An instance variable is associated with each instance of a particular class. If a 
class defines an instance variable called, for example, name , then every instance of 
that class will have an instance variable called name . Like all variables in all 
programming languages, instance variables have values associated with them. 
Generally, you can both read and write these values. 
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Using Workspaces 

We will frequently use Workspaces in this book, so let’s review how they 
are created and used. 

Think of a Workspace as a blank slate that you can use as a free-form 
text editor for any purpose. You can have a theoretically unlimited num¬ 
ber of Workspaces open at one time (including none). 

To create a new Workspace, choose New from the File menu in any 
window that has such a menu. This includes the System Transcript and 
all browsers. When you create a new Workspace, IBM Smalltalk opens a 
window for it with the name Workspace. 

Notice that a Workspace has only one large text-editing pane (along 
with a few standard window icons, a File menu, and an Edit menu). You 
can, of course, move, resize, collapse, zoom, and close a Workspace. You 
can freely edit in the Workspace as well, but because the primary pur¬ 
pose of a Workspace is code experimentation and because extra car¬ 
riage returns in code can sometimes cause problems, text in a Workspace 
does not automatically “wrap.” 

If you close a Workspace containing text you’ve changed since last 
saving it, you’ll be asked if you want to discard the changes. 

We usually save a Workspace soon after creating it (unless its role is 
transitory). To do so, choose Save from the File menu and give the file a 
name. We’ve adopted the convention of using a WSP filename extension 
for Workspaces so we can differentiate them in our Smalltalk directories. 

You may find it useful to create a Workspace that contains helpful 
code fragments and call it something like USEFUL.WSP. If you follow 
this plan, be sure to comment the fragments liberally; it’s amazing how 
cryptic your own code can be six months after you write it! 

IBM includes a Workspace of useful preference-setting code that you 
can access by selecting Open Preferences Workspace from the Smalltalk 
Tools menu in the System Transcript. The Workspace contains a large 
number of useful code fragments ready for you to execute (in some cases 
after adapting them to your specific need). Figure 1-11 shows a Prefer¬ 
ences Workspace scrolled to show some user interface settings with which 
you may wish to experiment. 
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File Edit 


Preferences Workspace 


[IBM Smalltalk System Preferences 


USER OPTIONS 


Set whether the user should be prompted for the path name of the primitive 
source when modifying a user primitive method. 

EtTools record Use rPrimitive Path: false 


ERROR REPORTING 


I Initialize the error reporter. 
EmErrorReporter initialize. 



A Preferences Workspace 


Using the Debugger 

The Debugger is one of the richest IBM Smalltalk tools. It combines the 
functions of traditional debuggers with browser and inspector capabili¬ 
ties to give you a single immensely useful tool. If you’re like most Smalltalk 
programmers, you’ll find yourself spending a lot of time in the Debugger. 

We’ll have frequent opportunities to explore the use of the Debugger 
as we build projects through the remainder of the book. For now, we 
want to take a top-level tour of the Debugger use just so you become 
familiar with its basic operation. 

Figure 1-12 shows the Debugger as it might appear if you simply 
pressed ( cntri ) - (Breai<) with no application executing in the environment. 
(You may have to hold these keys for a second or so, until you hear a beep.) 






BM SMALLTALK 


18 




j File Edit Processes Stack Inspector 

Value Report 




no variables selected 

± 

,±1 


\\ in ExceptionaiEvent class>>#initializeSyst 
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ExceptionalEvent>>#applyDefaultHandler: 

ExceptionalEvent>>#signaSUsing: 

±! 
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Mi... ... l-tl 


| Into | Over | Return j Resume 
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UlProcess 





Name: 3800 





Process State: suspended 





Priority: 3 





I Executing in: ExceptionaiEvent class»#initializeSystem 

i Exceptions 


Error string: User Break 





Resumeable: true 




±l 

dd __ 

warn 





Figure 1-12. 


A sample Debugger 


From this main debugging window, you can do everything you want to 
do to debug your Smalltalk code. You can open an inspector on a se¬ 
lected object in the window by selecting the appropriate option from the 
Edit, Inspector, or Value menu. You can open various browsers. (See, 
especially, the Stack menu, which lets you open numerous types of brows¬ 
ers with various options.) There is even an option on the Stack menu for 
copying the text in the Stack Trace. (See the information in the window 
just above the four buttons at the left center of the window.) 

Among the most useful things you can do in the Debugger appear as 
the primary options on the Processes menu. The browser options in the 
second group of items are particularly noteworthy. The ability to browse 
the receiving class of a message that’s involved in a bug is often very 
ill umin ating; you may think you were sending the message to a particu¬ 
lar type of object only to find out via this menu option that the message 
is actually being sent to a completely different kind of object. 

The options “Resume” and “Animate” are not often helpful because 
most of the time bugs create processes that can’t be resumed and, there¬ 
fore, can’t be animated. (Animation is a special kind of resumption in 
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which you can watch each step of the process execute.) When these op¬ 
tions are legal, however, they can be quite helpful. 

You will often want to terminate the process on which you are con¬ 
ducting the debugging operations because you’ve seen the problem and 
know how to fix it. 

Don’t overlook the Report menu, either. It allows you to create, either 
in a Workspace window or in a text file on the disk, a fill-in-the-blanks 
report form for you to complete and send to IBM if you need help with 
something really difficult. (You can also allow your users to use this same 
approach to send you error reports with lots of meaning to them, pro¬ 
vided that they own IBM Smalltalk, of course.) 

To explore the Debugger a bit more, open IBM Smalltalk and type the 
following line of code into the System Transcript: 

' a ' +6 

Now choose the text and execute it. You’ll see a Debugger window 
like the one in Figure 1-13. 


File Edit Smalltalk tools 


System Transcript 


(CJ 1994 International Business Machines Corporation 
All Rights Reserved 

(CJ 1990 - 1994 Object Technology Internat i ona l Inc. 
VM Time^f 



IBM Smalltalk Debugger 


File E dit Processes Stack Inspector Value Report 


sljnoEt Mn^rBdtoijr^Mn TjlPjppCT^si38 


n in ExceptionalEvent class»#initializeSysten| 
Signal>>#evaluate: 

Exception alEvent»#app!yDefaultHandler: 

ntinn alFwf ntYYtf oinnall loirwr _ 


Return 


Resume 


UlProcess 
Name: 3802 

Process State: suspended 
Priority: 3 

Executing in: ExceptionalEvent class»#initializeSystemExceptions 

Error string: String does not understand + 

Resumeable: false 



Figure 1-13. 


A Deboggier open on a syntax error in the System Transcript 
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The first thing to notice is the message in the upper-left portion of the 
window. It says, “String does not understand +” followed by some other 
stuff that sounds (and, for the most part, is) less interesting. We know 
that the bug was caused by sending a message called + to an instance of 
the class String. Forget for the moment that we already knew that was a 
silly thing to do. 

The first several lines in the Stack Trace (the scrolling list immedi¬ 
ately below where the error message appears) are generally not very 
helpful. They present messages dealing with the error-handling process 
itself and therefore don’t provide much insight into what is happening 
with the code that has gone awry. 

Scroll down in the Stack Trace list if necessary until you see a line 
that says “UndefinedObject»#DoIt.” Select that line. Notice that the large 
text-editing area at the bottom of the Debugger window has highlighted 
the code we entered in the System Transcript. This is the beginning of 
the process that is executing our code. (This fact is a handy thing to keep 
in mind; anytime you are testing code in a Workspace or the System 
Transcript, you will find your code associated with a step in the stack 
that looks just like this one.) 

Click on the line above the currently selected line in the Stack Trace. 
Now notice in the tall, skinny pane to the right of the Stack Trace that 
there are two entries; “self’ and “aMessage.” The first is selected. To the 
right of it in the rightmost part of the window, we can see that self has a 
value of ‘a.’ Let’s inspect that value just to see whether it is indeed a 
String as we suspect. From the Inspector menu, choose Inspect. An in¬ 
spector like the one shown in Figure 1-14 appears. 


File Edit Processes Stack Inspector Value Report 


Strina does not understand ±* in UlProcess: 


String[Qbject|>>ff error: _ 

UndefinedObject>>#Doit 


Into 


Over 


Return 


doesNotUnderstand: aMessage 

"Report to the user that the receive^ 
implement any methods for the me 
argument aMessage." 


self error: fself doesNotUnderstanc 



An Inspector open on a String object 
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From the title bar of the Inspector window, we can confirm that this is 
indeed a String object. In fact, we can determine that it has one character. 

Similarly, you can click on aMessage in the Debugger window and 
then inspect it to see what the current selector and argument are. 

You can see the process at work here. In summary, when you are 
working with the Debugger, you will often use a three-step procedure: 

1. When a problem arises and a Debugger window appears, you will 
examine potentially meaningful messages in the Stack Trace. 

2. At some point you’ll identify a likely suspect for the source of the 
error. You’ll then open an Inspector on a specific object or message. 

3. Inspecting the values of these objects will often lead directly and 
quickly to the source of the error. 


There is, of course, a great deal more to the Debugger. We’ll revisit it 
several times in later chapters, each time becoming a bit more sophisti¬ 
cated in its use. There are even some kinds of errors for which the 
Debugger isn’t much help. We’ll see one of those in Chapter 3. 



CHAPTER 


The IBM Smalltalk 




In Chapter 1 we examined the programming tools in IBM Smalltalk. In 
this chapter we focus on the other two major components of the envi¬ 
ronment: the language and the class library. The first part of this chap¬ 
ter reviews the basic syntax of the IBM Smalltalk language. Much of this 
material duplic ates information found in the IBM Smalltalk documentation, 
but it summarizes and presents the syntax of the language in a useful 
way. The second part of this chapter discusses the major classes in IBM 
Smalltalk’s class library. These are the classes with which you must be 
most concerned in a huge percentage of your programming work. 

At the end of this chapter, then, you should be comfortable with the 
syntax and structure of IBM Smalltalk and be better equipped to pro¬ 
gram in it. 

Reviewing Basic Smalltalk Syntax 

Everything that happens in an IBM Smalltalk application is a result of a 
message being sent to an object that supports a method of the same 
name as the message. IBM Smalltalk programming most broadly con¬ 
sists of defining objects with methods, where methods send messages to 
other objects. 

We can look at IBM Smalltalk syntax on two levels: message passing 
and method execution. 
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Message-Passing Syntax 

All messages in IBM Smalltalk have the same basic syntax. The receiver 
of the message (the object to which the message is being sent) appears 
first, followed by the message itself. For example, here we send the in¬ 
spect message to open an Inspector window on the class Set (you can try 
t hi s yourself by entering the following into a Workspace or Transcript 
and selecting execution in the pop-up menu): 

Set inspect. 

The receiver, the class Set itself, is passed the inspect message, in effect 
telling the class, “inspect yourself.” This order of expression is opposite 
that used in traditional programming languages. This reversal frequently 
confuses Smalltalk programmers experienced in other languages. They 
are tempted to write the line as “inspect Set” because they are accus¬ 
tomed to placing commands ahead of the data structures or items on 
which they operate, in what is also the natural sequence of verb-object 
in English declarative sentences. 

A message passed to an object can consist of a single word (such as 
inspect ) or of a series of words. Each word of the message is referred to 
as a keyword. The message being sent, whether containing one keyword 
or several, is called the selector. By convention, a keyword that ends 
with a colon expects an argument (like a parameter in other languages) 
to be associated with it; one without a colon does not expect an argu¬ 
ment. Multiple arguments may be associated with a selector, resulting in 
long message names like this one: 

labelArray:lines:selectors: 

Note that this is a single message selector consisting of three keywords 
(, labelArray .-, lines:, and selectors:), each of which requires an argument. 
(This is like passing a parameter in another language.) The message 
name will appear in a browser as shown above. Each colon signals you 
as a programmer of the need to supply an argument. The colons also 
signal the language compiler to look for an argument there. 
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One other type of message, called a binary selector , requires an argu¬ 
ment but has no colon. The clearest examples are math operators, like 
the addition sign (+). The following line of IBM Smalltalk code sends the 
message + to the object 6 and passes an argument of 4 in the process: 

6 + 4. 

You can evaluate expressions from anywhere you can edit text, such as 
a Workspace or the System Transcript or from within a method defini¬ 
tion. To send a message from a Workspace or the System Transcript, 
type the message, select it, and then choose one of the execution options 
from the pane menu. The choice of whether to execute or display the 
expression is important. For example, if you type the above addition 
message into the System Transcript, highlight it, and then choose Ex¬ 
ecute from the menu, nothing appears to happen. In fact, IBM Smalltalk 
carries out your instructions by adding 6 and 4. You didn’t tell it to do 
anything with the result, so it didn’t. Highlight the same expression and 
choose Display from the menu and the answer appears in the window, 
highlighted. 

The menu also has an Inspect option, which allows you to directly 
inspect the highlighted text representing an object. In the above example, 
the inspect message could have been performed by simply highlighting 
Set and selecting Inspect instead of Execute. 

You will often find it necessary to send a series of successive mes¬ 
sages to the same object. To avoid repeating the name of the receiver 
object, use message cascading. Here, each message sent to the same 
object is followed by a semicolon until the final message is sent. The 
entire cascaded message group is terminated with a period like any other 
Smalltalk message. For example, the following code adds strings to the 
collection and displays the collection: 

Set new 

add: 'Hello': 
add: 1 Goodbye’: 
printstring. 
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Method-Definition Syntax 

Follow the syntax shown in the code sample below when defining a new 
method in the text area of a browser: 

messagePattern 
"comment" 

| temporaries | 
statements 

The messagePattern includes the method selector and placeholders for 
the variable names used to refer to arguments in the method. It there¬ 
fore defines how to phrase a message you wish to send to this object to 
execute this method. 

Comments are optional. However, the template for defining a new 
method in IBM Smalltalk includes them, and experienced programmers 
and designers strongly recommend them. Most comments, as you can 
discover by browsing the system, indicate the type of value returned, or 
answered, by the method. This format is helpful because it clarifies what 
happens when a programmer strings together selectors in a single state¬ 
ment, which is a common Smalltalk practice. With comments describing 
the types of objects returned, you can read the code to be sure the proper 
kind of object is being dealt with at each step. Any brief comment that 
describes the purpose and return value of your method should be suffi¬ 
cient. (If your method requires copious comments to make it clear, it is 
probably too large or monolithic. Try to break it into smaller, easier-to- 
describe components that are more focused.) 

In IBM Smalltalk, you can add a comment to a class definition by 
selecting the class in a browser and then choosing “Comment” from the 
small drop-down combo box in the upper-right corner of the lower por¬ 
tion of the window as shown in Figure 2-1. 

This is a noteworthy improvement in IBM Smalltalk over earlier re¬ 
leases of other Smalltalk dialects (though the others are beginning to 
adopt a similar technique). Class comments were difficult or impossible 
to enter and maintain in other versions of the language. 

You can see all of the comments for the methods defined in a particular 
class by selecting the class in a browser and choosing “Summary” from the 
same pop-up menu we just used to enter a class comment. The summary 
includes the message selector and comment and is often an excellent way 
to obtain an overview of the behavior of a class you are exploring. 
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Figure 2-1. 


A class comment in a browser 


Temporary or local variables in a method must be defined at the be¬ 
ginning of the method. Such variables are placed between two vertical 
bars (created with the shifted backslash on the standard IBM PC key¬ 
board). If more than one variable is needed, they are separated from 
one another by spaces. 

The statements portion of the method definition actually performs 
some operations when the method is invoked. We are going to show that 
process now. 

Let’s examine a typical IBM Smalltalk method to see how the various 
pieces look and behave. 

1. Open an application browser and choose the application kernel. 

2. Double-click on the kernel to show its sub application and choose 
CLDT (which stands for Common Language Datatypes). 

3. In the class list to the right of the application list, select Integer (it 
is near the bottom of the list). 

4. Select Instance Category CLDT-API 

5. In the method list to the right of the class list, select gcd: 

6o Examine the code in the text-editing portion of the window. 

You can see from the gcd: code listing and comment that the method 
takes an integer as an argument. If a noninteger argument is supplied, 
the method coerces the argument to be an integer and then performs its 
mission. Since it is a member of the class Integer, its receiver must also 




IBM SMALLTALK 
28 - 


be an integer value. The comment tells you how the method works and 
what it returns. 

Notice that this method defines three temporaries called x, z/, and 
temp. Note from the statements that make up the executable portion of 
the method definition that all of these variables are used within the 
method definition. 

You have probably never seen this method definition before. (That’s 
why we chose it!) But just by reading the source code and the comment 
you can tell what it does and how to use it. How could you use the method 
in the System Transcript to find the greatest common denominator be¬ 
tween the numbers 12 and 18? Just type the following line, highlight it, 
and choose Display from the pop-up menu: 

12 gcd: 18 

IBM Smalltalk returns the value 6 as the largest integer that can divide 
evenly into both 12 and 18. 

Essential Applications and Classes 

IBM Smalltalk divides your view of its world into applications. Classes are 
defined within the context of applications. In fact, a given class can be de¬ 
fined within only one application, but it can be extended in any number of 
applications. By extending, the application adds methods to a class that is 
already defined in another application. In this section, we’ll take a look at 
the most important applications in the IBM Smalltalk image and, within 
each application, at the most important classes it defines. 

The IBM Smalltalk image comes equipped with approximately 75 
applications, which in turn contain several hundred classes. When supple¬ 
mented with extra add-ins, examples, and other helpful files shipped 
with the program, these numbers get considerably larger. 

As you build applications, acquire code from other sources (such as 
the disk provided with this book), and work with the environment, the 
number of classes and methods can grow substantially. If you had to be 
familiar with all of these classes and methods, you might never be confi¬ 
dent as an IBM Smalltalk programmer. 

Fortunately, many applications and classes in the IBM Smalltalk hierar¬ 
chy either are used primarily by the system or have such esoteric functions 
that you will probably never need them. In this section, we’ll identify the 
applications and classes with which you will want to become most familiar 
and comfortable as you begin your exploration of IBM Smalltalk. 
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We won’t supply a great deal of information about each class in this 
list (although we will elaborate a bit on a few classes). The documenta¬ 
tion supplied with the system contains detailed descriptions of all classes 
and methods. We will demonstrate the use of these classes in greater 
detail when we use them to build projects later in the book. 

The primary applications with which you will be concerned as you 
build IBM Smalltalk applications are: 

n Kernel 
a Core 

a CLDT (Common Language Datatypes) 
b CPM (Common Process Model) 
a Common Graphics 
b Common Widgets 
b CwPrompters 
b Common File System 

Each application has one or more classes with which you will need to 
become at least somewhat familiar. 

The kernel Application 

The Kernel application defines only one class: Object. It also acts as the 
parent to three other important subapplications we’ll be discussing later 
in this chapter: Core, CLDT, and CPM. 

Object is an abstract class that defines behavior common to all 
objects in the IBM Smalltalk class hierarchy. You will create only 
subclasses of this class; you will never create an instance of it. 


The Object class is one of several abstract classes in IBM Smalltalk. An abstract 
class is a place to collect and organize behavior common to a number of classes. 
You almost never create an instance of an abstract class; its purpose is to provide a 
convenient place for behavior common to other, more directly useful classes. You'll 
see what we mean when we study several abstract classes later in this chapter. 
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Tie Core ^application 

The application Core is a subapplication of Kernel. Most of its classes 
are fairly esoteric and of interest only to the fairly advanced IBM Smalltalk 
programmer. It is worth noting in passing that three of its classes—Be¬ 
havior, Class, and Metaclass—are central in the overall behavior of 
classes in the IBM Smalltalk library. These classes define methods that 
deal with such things as lists of methods defined by classes and are often 
useful when you want to build new or extended Smalltalk development 
tools in your own work environment. 

The classes Block and Context are of somewhat more than passing 
interest. Instances of these specialized classes work together only in con¬ 
junction with blocks of Smalltalk code (groups of statements enclosed in 
square brackets). Among other things, these classes handle loops using 
whileTrue: and whileFalse: methods. 

The CLDT ^application 

The CLDT subapplication is one of the most important in your IBM 
Smalltalk arsenal. It defines most of the classes used to store information 
in data structures and primitive data type objects. Figure 2-2 is a partial 
hierarchical listing of this subapplication and its important classes. (We 
have omitted parts of the class hierarchy, so Figure 2-2 is not complete.) 

Boolean, False, True 

The classes False and True, both subclasses of Boolean, are logical classes 
used in conditional processing throughout IBM Smalltalk as well as in 
logic operations. Logical expressions return Boolean results that are 
then typically tested for their outcome using methods with names like 
ifFalse: and whileTrue: and iJTruedfFalse:. 

Collection Classes 

As you can see from Figure 2-2, a significant part of the important classes in 
the CLDT subapplication are subclasses of Collection. The class Collection 
is an abstract class that defines the behavior for a basic data structure 
used to store objects in groups. The objects may be stored in any of 
several forms, sorted or unsorted, and paired with other key objects in 
Dictionary form.The four main subclasses of the class Collection are: 
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■ Bag, in which duplicate elements are allowed and the elements of 
which are stored in no particular order 

■ SequenceableCollection, an abstract class in which duplicate el¬ 
ements are allowed but the elements of which either are stored in 
some predetermined order (sorted) or are at least accessible by 
an integer index because they are stored sequentially (thus the 
name of the class) 

■ Set, in which no duplicate elements are allowed and the elements 
of which are stored in no particular order 

■ Dictionary, a set of associations consisting of related pairs of ob¬ 
jects, the first of which is a unique key (usually but not always a 
symbol i and the other of which is a value. Each key has an associ¬ 
ated value, and values are retrieved from a Dictionary by refer¬ 
encing their keys. 


Object 

Boolean 

True 

False 

Collection 

Array 

Bag 

Dictionary 

OrderedCollection 

Set 

SortedCollection 

String 

Symbol 

Magnitude 

Association 

Character 

Date 

Float 

Fraction 

Integer 

Time 

Point 

ReadStream 

ReadWriteStream 

Rectangle 

WriteStream 


Figure 2-2. 


Important Classes in the CLDT So bappl acation 
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There are two notable differences here between IBM Smalltalk and other dialects. 
First, what IBM Smalltalk calls a SequenceableCollection is usually referred to in 
other dialects as an IndexedCollection. Second, in other dialects, a Dictionary is a 
subclass of Set 


The class SequenceableCollection has two main subclasses, both of which 
are abstract classes: AdditiveSequenceableCollection and Arrayed- 
Collection. These two classes in turn have important concrete subclasses 
with which you will have frequent need to work. 

The important subclasses of AdditiveSequenceableCollection are 
OrderedCollection and SortedCollection. The differences between these 
classes are important in designing good Smalltalk applications. An 
OrderedCollection is one in which the order of elements is important to 
the program but maintained by the programmer. You can insert elements 
into or at the beginning or end of an OrderedCollection as needed. In¬ 
stances of this class can thus be used to mimic the behavior of such tradi¬ 
tional computing data structures as arrays, queues, and stacks. A 
SortedCollection, on the other hand, is a collection whose order is main¬ 
tained by the environment in accordance with a special piece of code you 
write called a sortBlock. You don’t add elements arbitrarily to such an 
object; rather, you use a generic process of telling an instance of 
SortedCollection to add a new element to itself; it then places the new ele¬ 
ment in a way appropriate to the sorting instructions you have given it. 

Class ArrayedCollection has a number of subclasses; in fact, it is one 
of the most specialized classes in the IBM Smalltalk class library. For 
most purposes, you’ll work primarily with three of these subclasses: Ar¬ 
ray, String, and Symbol. 

An Array, like most other collections, can contain a mixture of any 
variety of object types. 

A String is a group of characters in an indexable sequence. We 
don’t usually think of strings as collections of individual characters 
from a programming standpoint, but IBM Smalltalk maintains consis¬ 
tency even at this detailed level. 

A special type of String is a Symbol, which consists of guaranteed 
unique sequences of characters that the system uses in special ways. 
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Magnitude and Subclasses 

The abstract class Magnitude is home to a number of commonly used 
classes in IBM Smalltalk, including most notably: 


m Association 
m Character 
h Date 
m Number 
m Time 

We’ve already looked at Association, which is used primarily in con¬ 
junction with the powerful and extensively used Dictionary class. Let’s 
take a look at the other four Magnitude subclasses. 

Character defines the behavior of all printable and nonprintable ASCII 
characters in the system (those represented by ASCII codes from 0 to 
255 or double-byte characters from 0 to 65535). 

Date represents a particular day and can be used to manipulate 
months, days of the month, days of the week, years, weekdays, week¬ 
ends, and other calendar-related activities. (We’ll spend a good deal of 
time with this class in Chapters 6 and 7.) 

The class Number is itself an abstract class that manages all types of 
numeric values. This class includes the basic behavior for all numbers, 
chief among which are Float (numbers expressed as IEEE double-preci¬ 
sion, floating-point values), Fraction (numbers expressed as one num¬ 
ber divided by another), and Integer (whole numbers with no decimal or 
fractional parts). 

Instances of Time are a particular time of day you can use to manipu¬ 
late time-related information such as hours, minutes, seconds, and frac¬ 
tions of seconds. 

Point 

The next CLDT class we’ll look at is Point. This class describes objects com¬ 
posed of a pair of x-y coordinate values defining a point on the computer’s 
display. Points are important for drawing and graphics, but they are also 
often used to locate and size windows and widgets within windows. 
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Rectangle 

An instance of the class Rectangle describes a rectangular area either 
by defining its upper-left and lower-right corners (in other words, the 
absolute location of both coordinates) or by describing its upper-left cor¬ 
ner and an extent (length and width) for the rectangle. 

Rectangles are used primarily for graphics and-drawing, but like points 
they are also important in defining the sizes and relative positions of 
widgets in a window. 

Stream 

The class Stream and its subclasses are used to define input/output path¬ 
ways for your application. An instance of a Stream-type object contains 
methods that handle such things as defining the current position of the 
read/write operation in the stream, adding information to a stream, re¬ 
turning some portion of the stream’s contents to a requesting object, 
and relocating the position of the read/write operation. 

You can define streams to be read-only (using instances of the class 
ReadStream), write-only (with WriteStream) or read/write (with 
ReadWriteStream). 



Unlike other Smalltalk dialects, IBM Smalltalk handles files differently from all 
other stream-type objects. Files are handled in a separate application called the 
Common File System, which we will discuss later in this chapter. 


The Common Process Model 

The Common Process Model (CPM) application is assigned the responsi¬ 
bility of arbitrating among processes and managing the flow of pro¬ 
cesses within the IBM Smalltalk model of the world. The CPM applica¬ 
tion is much more fully developed in IBM Smalltalk than in earlier, more 
traditional dialects of the language. This is due in large part to the fact 
that IBM OS/2 is a multithreaded environment. IBM had a lot of incen¬ 
tive to create a robust set of classes to support threading. 

You will find yourself using the following classes related to thread¬ 
ing and the CPM in your applications from time to time: 
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m Process 
m ProcessScheduler 
m Semaphore 
h Delay 

Chapters 16 and 17 delve into multithreading in greater detail. 

Process 

An instance of the class Process represents a sequence of messages on 
an independent thread of execution. Each thread in a multithreaded 
application or environment will include an instance of this class. 

The ProcessScheduler 

This class has a single instance in the IBM Smalltalk environment. The 
instance is referred to by the global variable Processor. It is responsible 
for managing all the processes in the environment. 

Semaphore 

Instances of the class Semaphore work with instances of Processor to 
coordinate multiple-process applications. This class keeps track of mes¬ 
sages and signals being passed back and forth in the environment. Sema¬ 
phore objects are turned on and off to allow and block specific process 
flows, acting as traffic cops in the multiprocessing world. 

Tie Comnoit Graphics Application 

Classes in the Common Graphics application have names that all begin 
with the letters “Cg.” These classes define data structures and objects 
responsible for displaying graphical objects. 

The most important subclasses of this application are as follows: 

m CgWindow, instances of which represent an area of the screen, 
usually but not always the visible area of a user interface widget. 
(Widgets are explained in the next section.) Each widget has a 
window. CgWindow essentially acts as a link between Common 
Graphics and Common Widgets applications. 

■ CgDrawable, instances of which represent areas of the screen 
that can be drawn upon. Instances of this class always hold either 
a CgWindow or a CgPixmap object, since these are the only two 
drawable objects in IBM Smalltalk. 
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h CgFont and CgFontStruct, which are closely related. A CgFont 
object represents a font of a given size and style that has been 
loaded into memory and is available for displaying text and sym¬ 
bols. A CgFontStruct is a data structure that stores information 
about a CgFont such as the number of characters in the font, 
height, average character width, and the like. 
h CgScreen, representing a single hardware output device, con¬ 
tains information about the device such as dimensions and depth 
of pixels (for color or gray-scale drawing), 
a CgGC, sometimes simply referred to as a GC or a Graphics Con¬ 
text, is a data type that stores drawing attribute information such 
as current color, line width, and line style. 

The Common Widgets Application 

The graphics in IBM Smalltalk are built on the X-Window base popular¬ 
ized on UNIX computer systems. This base gives the graphical display 
of an object sufficient flexibility and platform independence that objects 
can be drawn on a number of host platforms without modifying the 
drawing code. 

A widget is a user interface component. The topmost level of widgets 
is the CwShell object, whose only purposes are to act as a container for 
other widgets and to negotiate with the host window manager for posi¬ 
tioning and display of its contained widgets. 

All concrete widget classes are subclasses of CwPrimitive (objects 
that cannot have children widgets associated with them), CwComposite 
(objects that can have zero or more children), or CwShell (objects that 
always have exactly one child). Primitive widgets are always the chil¬ 
dren of another widget. 

In Chapters 10 and 11, we will focus attention on the graphical world 
of IBM Smalltalk and explore many widget classes in depth. For now, 
the most important and useful widget classes are these: 


a CwList, which implements list boxes and related objects 
m CwPushButton, which implements not only buttons but also 
menus 

m CwText, where editable and noneditable text objects are handled 
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The CwPrompters Subapplication 

IBM Smalltalk defines a number of classes that are useful for implementing 
simple user interactions, either as entire interfaces for small applications or 
as portions of la rger, more complex and interesting interfaces. These classes 
are all defined in the CwPrompters subapplication. 

You will fmo the frequent need for three different types of prompters. 
CwTextPrompter requests the user to enter some text: 



CwMessagePrompter requests the user to select a response indicated by 
a push-button object: 



Finally, CwFileSelectlonPrompter displays a system-specific file selec¬ 
tion dialog. 
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The Common File System 

The Common File System features one subapplication that is of interest 
to us. The CfsStreams subapplication has a class CfsFileStream for which 
you will have frequent use as you read and write information to and 
from files on the system disk. 

The CfsFileStream class, in turn, has subclasses for creating streams 
that are read-only (CfsReadFileStream), write-only (CfsWriteFile- 
Stream), and read/write (CfsReadWriteFileStream). 

Chapters 14 and 15 focus on the Common File System and its use in 
constructing real-world IBM Smalltalk applications. 
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In this chapter we will build our first IBM Smalltalk project. We will 
apply the lessons learned in Chapters 1 and 2 to design and construct a 
small applicati on. Then we’ll learn how to make effective use of the IBM 
Smalltalk environment by consolidating code. As part of this project, we 
will also learn more of the capabilities of the IBM Smalltalk debugger. 
We will work with the following built-in classes: 

n CwTextPrompter 
■ C wMess agePrompter 
a SortedCollection 

In addition, we’ll create our own class called Prioritizer. 

Project Overview 

We will build a project called Prioritizer. This handy little program lets 
you enter a list of items in any order, then helps you through the process 
of ranking these items from most to least (most to least important, most 
to least expensive, or any other ranking criterion you desire). In other 
words, in Prioritizer, the user is the comparison operator which deter¬ 
mines how the items are sorted, rather than the more common “less 
than” or “greater than” comparison operator. 

Everything is a trade-off. You encounter decisions in every aspect of 
your life. The Prioritizer application could help focus trade-off decisions 
between or among alternatives by forcing you to look at each alternative’s 
relative value when compared to each of the other choices. (We’ll see 
soon how this works in practice.) 
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Designing the Project 

Viewed at its simplest level, the Prioritizer application converts an in¬ 
stance of the class Set into an instance of the class SortedCollection, 
ranking entries in the original object as the user describes the value or 
importance of each element against each of the others. 

Prioritizer asks the user for individual items to be prioritized, allow¬ 
ing him to enter as many such items as he wishes. When he has entered 
all of the items, he simply presses the (Enter) key. Prioritizer goes through 
the choices and asks the user to make evaluations between pairs of op¬ 
tions. It then tracks the user’s responses and ends up with a list sorted in 
the order in which the user specified.To make Prioritizer do this, we will 
need program design elements that: 

m Prompt the user for individual items to be prioritized 
h Ask the user to rank pairs of elements in the list, answering for each 
pair the question, “Is this one more important than that one?” 
a Display the resulting sorted list 

Building the Project 

We will begin to construct the Prioritizer by trying some of its key ele¬ 
ments in a Workspace and testing them iteratively. When we have these 
pieces working, we can copy and paste them into a single text-editor 
portion of a browser as we define the Prioritizer class in its own right. 

Let’s work with the tasks in the order listed above. We must first build a 
routine to prompt the user to enter a list of items to prioritize. We need a 
way to ask the user a question, capture the user’s response, and add it to 
the growing list of items we’ll sort later according to the user’s instructions. 

In this case, the classes we use derive quite naturally from our narra¬ 
tive description of what the program should accomplish. 



This procedural approach is seldom the best way to approach a Smalltalk project, as 
we will see in Chapter 4. Later projects in this book take a much more object- 
oriented approach to design. 
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We need IBM Smalltalk classes that let us pose questions to the user 
and accept the user’s responses. Looking through the IBM Smalltalk Class 
Library diagram in Chapter 2, you can probably pick out one or two 
likely candidates. We’ll use an instance of the class CwTextPrompter for 
the initial user interaction (gathering items to sort) since we need a free¬ 
form user response, and an instance of CwMessagePrompter for the 
sorting process where we only need to allow the user to answer “Yes” or 
“No” to a question. 

Exploring the Class CwTextPrompter 

An IBM Smalltalk CwTextPrompter is a small window with one text¬ 
editing area, a message area, and an OK and Cancel button. Figure 3-1 
shows a typical CwTextPrompter. 

If you open a browser on the class CwTextPrompter and then expand 
the Instance Methods view to include the class’ direct superclasses, you’ll 
quickly find that a CwTextPrompter object defines four methods that 
hold some promise for the Prioritizer: 


eh answerString: 
h messageString: 
m title: 

■ prompt 


You can probably tell from the names of these methods what they do. 
The answerString: method defines the default answer for the user; in 
our case, we don’t want to offer a suggested response to the user. In fact, 
we’re going to exploit the fact that the user clicks the OK button while 
this field is blank in order to stop asking the user for items. So we won’t 
even use the answerString: method. The messageString: method is where 



Figure 3-1 


Atypical IBM Smalltalk CwTextPrompter 
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we put the question we want the user to answer. We’ll call on the title: 
method to put the name of the application into the CwTextPrompter’s 
title bar. It isn’t quite so obvious as the others, but the prompt method 
actually displays the prompter and handles the user’s interaction with 
it, returning nil if the user cancels the dialog, or returning the user’s 
response if the OK button is clicked. 


Creating a CwTextPrompter 

Open a new Workspace in your IBM Smalltalk environment and type the 
following code: 

anotherltem | 

anotherltem := (CwTextPrompter new) 
messageString: 

‘Something to prioritize? (or leave blank)’; 
title: ‘Prioritizer Demo’; 
prompt. 

A anotherItem 

Select all of this text and select Display from the pane pop-up menu. 
The result should look like Figure 3-2. 



Figure 3-2. 


Creating a CwTextPrompter from a Workspace 
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When you type text into the prompter and press (Enter) , IBM Smalltalk 
displays your response in the Workspace window. (This points out an 
important aspect of Smalltalk programming; we can execute code frag¬ 
ments to help us understand a problem or choose an approach to its 
solution.) 

Let’s look at what this code fragment does. 

The first line sets up a local variable called anotherltem in which to 
store the user’s entry. In the final application, the user will be entering 
more than one item and this name will make the code more readable. 

The next expression creates a new instance of the class 
cwTextPrompter, assigns its ultimate value to the anotherltem instance 
variable, and sends this new object the message messageString: with 
the parameter shown between single quotation marks. 

We cascade the next two messages (as described in Chapter 2). The 
first is the title: message, which places its string argument into the title 
of the prompter window. The second is the prompt message which, as 
we know, creates and handles the event management of the window. 

The last line returns the user’s entry in the prompter. 

Rather than returning the item entered by the user, the Prioritizer 
needs to create a new object in which to store each of the user’s entries. 
What kind of object should this be? It must be able to hold more than 
one object, so it should be some kind of Collection (i.e., an instance of 
one of the subclasses of the abstract class Collection). Collection has a 
number of immediate child classes, including Bag, Dictionary, and Set. 
A Dictionary stores pairs of values as related to one another—a key 
entry and a value entry, much like a real dictionary in which the key is 
the word and the value its definition(s). It is obviously overkill for a simple 
list of objects. 

We can make a straightforward choice between an instance of class 
Bag and class Set. Bags can have duplicate elements, sets cannot. In our 
case, the user would only by accident make a duplicate entry in a list of 
choices to be prioritized. Since we want to ensure that the resulting list 
has only one entry for each choice to be ranked, we will use an instance 
of class Set. 

If we simply define a new local variable to hold the accumulating list 
of objects and modify our earlier listing to keep adding to this set, we 
encounter a problem: how do we get the process to stop? 

We have already anticipated the need for the user to be able to indi¬ 
cate when the last entry has been made. We chose to let the user leave 
the prompter blank. Pressing the (&TT) key (or OK button) without enter¬ 
ing any text signals that the list is complete. We can handle this situation 
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with a simple conditional test. Until the user enters a blank, we keep 
posing a new CwTextPrompter asking the user for another item to be 
prioritized. If the user’s entry is blank, we are finished. 

Here is the complete code for constructing and displaying a set of 
choices entered by the user: 

| items anotherltem | 
items := Set new. 

[(anotherltem := CwTextPrompter new 
messageString: 

'Something to prioritize? (or leave blank)'; 

answerString: ''; 

title: 'Prioritizer Demo'; 

prompt) = ''] 

whileFalse: [items add: anotherltem]. 

A iterns 


(Do not type a space between the single quotation marks in the above 
code.) 

Select this text and choose Display from the pane pop-up menu. When 
you enter a few answers and press the (Enter) key in an empty prompter, 
the result should resemble Figure 3-3. Note that IBM Smalltalk indeed 
returns a Set. You might enter a duplicate value to verify that Set works 
as advertised. Of course, if Cancel is clicked, nil will be added. 


items := Set new. 

[(anotherltem := CwTextPrompter ne 

messagestring: 'Something to prioritize? for leave blank]' 
answerstring 
title: 'Prioritizer Demo' - 
prompt] = "] 

whileFalse: [ items add: an otherltem 
‘items 

Setf'Jeanne' 'Dan' 'Carolyn ' 'Scott' 'Nan 


EH 


ElUHBl Set returned l>V prompter interaction 
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Sorting the User’s List 

More than one item in the list of objects will be sorted, so we know that 
we will probably be dealing with a subclass of the class Collection. The 
Class Library diagram reveals a class called SortedCollection (a sub¬ 
class of AdditiiveSequenceableCollection which is in turn a subclass of 
SequenceableCollection) that sounds like it should do what we want. 

Reading the description of this class proves our intuition to be right. 
Note that any instance of this class accesses a block of code known as 
the sortBlock. The sortBlock takes two arguments and returns the Bool¬ 
ean true if the first argument is higher in the sort order defined by the 
block than the second argument and false if not. 

We want exactly this kind of binary comparison—“Is x > y?” —in our 
Prioritizer, so we have a clear-cut choice of class for this part of our 
project. 

It turns out that this is the only aspect of the class SortedCollection 
we need in our project. Later in the book, you will make frequent and 
extensive use of this class and its powerful methods. 

It might occur to you during the course of designing the Prioritizer 
application simply to add a prioritize method to the class Sorted¬ 
Collection. But doing so would be inefficient because, as you can see 
from its description, the class SortedCollection sorts elements as it adds 
them to an instance of this class. A complete sort would occur each time 
an element wa s added to an instance of the class and then the prioritize 
method would force another sort. The user would be forced repeatedly 
to compare some items—obviously a poor use of the user’s time. 

Now let’s add the sorting capability to our code. To do so we define a 
sortBlock to specify how the items are to be sorted. The sortBlock will 
execute for each pair of items in the set called items and return an in¬ 
stance of class SortedCollection that we’ll call priorities. 

We need to define the sortBlock to ask the user to decide between the 
two priorities we have gathered, ranking one of them as more important 
than the other. Our first impulse is to use another CwTextPrompter ob¬ 
ject for this interaction. But it is better to let the user just click on but¬ 
tons that say something like “Yes” and “No” in response to a question 
about the relative importance of two priorities. As you know, CwText¬ 
Prompter objects lack such capabilities. We’d almost have to supply a 
default answer of Yes or No for the user to accept or change, which 
would lead to an unattractive interface. 
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Actually, the situation is more complex than that. Since a sortBiock must return a 
Boolean value, we couldn't even use Yes or No as the answer. We'd have to use 
True or False. This would sound unnatural. To make things even more messy, the 
answers are case-sensitive. 


Lets find a better user interface device. We really want an object that 
displays a string we can supply and provides the user with two buttons 
(preferably labeled “Yes” and “No”) from which to choose an answer. 
This sounds like a job for another prompter-type widget, so lets look 
around in that part of the class library. 

Some exploring uncovers two likely candidates for the task at hand: 
CwMessageBox and CwMessagePrompter. Both allow us to display a 
string and offer the user buttons through which to interact with our 
application. Either would do here, as it turns out, but we’ve decided— 
largely but not completely arbitrarily—to go with an instance of 
CwMessagePrompter. We felt a slight preference for this widget because 
it seemed a little more general and because programming its content 
looked a little less intimidating. 

Let’s experiment with a CwMessagePrompter in a new Workspace, 
as is our present pattern. Open a new Workspace, type in the following 
code fragment, select it all, and display it: 

CwMessagePrompter new 

title: ‘Prioritizer Demo’; 
messagestring: ‘This is just a test, ok?’; 
buttonType: XmYESNO; 
iconType: XmlCONQUESTION; 
prompt. 

The result should look something like Figure 3-4. Notice the use of 
the two constants, XmYESNO and XmlCONQUESTION, to define proper¬ 
ties of the prompter. As we mentioned in Chapter 2, this is a very com¬ 
mon practice in IBM Smalltalk. Note that these values, like everything 
else in Smalltalk, are case-sensitive. 
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Figure 3-4. 


Testing a CwIMessagePrompfer 


Now we’re ready to modify our growing single (and still unnamed) 
method to add the user-sort capability. We want to go through the Set 
generated by the user’s responses and ask for each pair of items whether 
one is more important than the other. Here is a variation on the code 
immediately a bove. Delete the last line of the code in your first Workspace 
(the line that returns the value of items) and add a new local variable 
called priorities to the list at the beginning of the code fragment. Then 
add the following code after the block of code that follows the whileFalse: 
method call: 

priorities := SortedCol1ection sortBlock: 

[:a :b | CwMessagePrompter new 
title: ' Prioritizer Demo'; 
messagestring: 'Does ', a printstring, 

' have a higher priority than 
b p r i n t S t r i n g , ' ?' ; 
buttonType: XmYESNO; 
iconType: XnICONQUESTION ; 
prompt]. 

priorities addAll: items. 

A p r i o r i t i e s . 

(We’ll look at the printstring method on line 4 in a moment.) 

Select the text of the method and display it. Enter two or three items 
to sort and then press (b^P) to signal the end of the list. Now when you 
are asked if one item is greater than another (see Figure 3-5), you can 
either press (e^T) or click on the Yes button to indicate that it is, or the 
No button to indicate that it isn’t. When you have supplied answers for 
all the pairs of values you entered, Smalltalk will return the value of 
priorities in its sorted order, according to your rankings. 
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Figure 3-5. 


Prompter asking for the ranking 


Displaying the Result 

We can display the results in a number of places when executing IBM 
Smalltalk programs. The Transcript window may be the most common, 
particularly in a simple application like the Prioritizer. We put text and 
symbols into the System Transcript by sending strings to a special sys¬ 
tem global variable called (appropriately enough) Transcript. There is 
always one and only one instance of the class EtTranscript and it is 
called Transcript. 

Following convention, we often use the message cascading technique, 
discussed in Chapter 2, to send a series of messages to a particular ob¬ 
ject, in this case the System Transcript. 

Recall that priorities contains an instance of class SortedCoIlection 
when we finish sorting it according to the user’s instructions. How do we 
display the contents of an object of this type? Since Transcript points to 
an instance of the class EtTranscript, we should be able to find out how 
it handles and displays information. Open a browser on the class 
EtTranscript. Look through its instance methods; you’ll find nothing here. 
In its parent, EtWorkspace, you’ll find one called show: that has some 
promise. But an examination of its source code reveals that it simply 
calls another method, nextPutAll: , so take a look at that method. It ap¬ 
pears to be what we want. 

Let’s change the last line in our working method so that instead of 
returning the value of the priorities variable, we display the value in the 
Transcript. Try this line in place of the current last line in the Workspace: 


Transcript nextPutAll: priorities 


Oops. You encountered your first real debugging session of your IBM 
Smalltalk career! We’re going to spend some concentrated time on the 
Debugger later in this chapter, but let’s take at least a brief look at it 
here. The window you generated should look something like Figure 3-6. 
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IBM Smalltalk Debugger 


File Edit Processes Stack Inspector Value Report 


n does not understand osSfI 


Q in ExceptionalEvent class>>#initializeSy| 
Signal»#eval ! uate: 

Except! on alEvent>>#applyDefaultHandler: 

! o n , o II Inmn' _ - 


Into 


Over 


Return 


Resume 


no variables selectet 


USProcess 
Name: 381 2 

Process State: suspended 
Priority: 3 

Executing in: ExceptionalEvent class»#initia!izeSystemExceptions 

Error string: SortedCollection does not understand asString 
Resumeabie false 


Debugger showing problem with new line of code 


The most important item to examine first when a Debugger shows up 
is the error message that appears in the upper-left corner of the win¬ 
dow. In this case, the salient portion of that message tells us that 
“SortedCollection does not understand asString.” (At this point, you may 
be scratching your head and reading through the code you just entered 
looking for a reference to this asString message that is causing all the 
confusion. Don’t bother. You didn’t send the asString message; someone 
else did. That’s one of the most difficult things for inexperienced pro¬ 
grammers to get used to. There’s a feeling that things are happening 
behind your back. Things are happening behind your back, but they’re 
good things once you understand them!) 

Examine the class SortedCollection in a browser and you’ll be able to 
confirm that such objects do not, in fact, understand the asString mes¬ 
sage. In fact, even if you ask the TrailBlazer browser to display inherit¬ 
ance all the way to the root Object class, you won’t find an asString 
method anywhere. So in this case it is not as important to find out which 
method is sending the asString message as it is to find out what we can 
do about the fact that it isn’t being understood. It seems apparent that if 
we can find a way to make priorities into a string, then we should be all 
right (since, presumably, the asString method either won’t need to be 
called to convert some other object to a string or, if it is called, it at least 
won’t be misunderstood). 
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Scrolling through the methods inherited by SortedCollection, we find 
one called printstring, which is defined in class Object. (That’s right; in 
IBM Smalltalk, all objects know how to display a string representation of 
themselves. This comes in awfully handy, as we’re about to see.) Change 
the offending line by adding a call to printString and see what happens: 

Transcript nextPittAl 1 : priorities printstring. 

Well, we’re a little closer, but this attempt displays the value oipriori¬ 
ties in an unacceptable fashion. What we want to do is print each item in 
the SortedCollection called priorities separately. It would be nice if each 
were on a separate line; it would be way cool if we could preface the list 
with some meaningful explanatory text. 

Try substituting the following lines (which we’ll explain in a moment) 
for the line we’ve been adding to the method: 

Transcript cr; nextPutAll: 'Your priorities are:';cr. 
priorities do: (‘element | Transcript nextPutAll: element; cr]. 

Now select all the code in the method and execute it. When you’re 
finished, a nicely formatted list of your priorities appears in the Transcript. 

The only really new items in this code are cr and do:. The first is easy 
to dispose of; it simply represents a carriage return and its purpose is 
strictly aesthetic. The do: message in this situation creates a looping 
condition involving the block of code that follows it and is enclosed in 
square brackets. It looks at each member of the SortedCollection, called 
priorities, and puts it into the Transcript, followed by a carriage return. 


You may be wondering what happened to the printString method that seemed so 
O' important a few lines ago. Well, we’ve made it unnecessary. Because we're treating 
^ each element of the SortedCollection separately, we’re actually sending the 

nextPutAll: message with a parameter that is a String. Strings understand the asString 
message (or don’t require conversion), so there's no need for us to force the issue 
with a redundant printString message. You'll find yourself doing this a lot in 
Smalltalk programming. You try something, find that it works, figure out why it 
works, and then find a more direct route to the same goal. 
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The Finished Prioritizer Method 

Now that we’ve built and debugged this new (and relatively complex) 
method, we will give it a name and find it a home. We’ll call it prioritize. 
For the sake of completeness, and so you can double-check your code 
before we proceed, here’s the entire method: 

prioritize 

“This method collects a bunch of items into an instance of Set. 

Then it lets the user sort them, placing the result into an 
instance of SortedCol1ection.” 

| items anotherltem priorities | 
items := Set new. 

[(anotherltem := CwTextPrompter new 
messageString: 

'Something 'to prioritize? (or leave blank)'; 

answerString: ''; 

title: 'Prioritizer Demo'; 

prompt) = ' ] 

whileFalse: [items add: anotherltem]. 
priorities := SortedCol1ection sortBlock: 

[:a :b | CwMessagePrompter new 
title: 'Prioritizer Demo'; 
messageStrirg: 'Does a printstring, 

' have a hie her priority than ', 
b printStrirg, '?'; 
buttonType: XmYESNO; 
iconType: Xir ICONQUESTION ; 
prompt]. 

priorities addAll: items. 

Transcript cr; nextPutAll: 'Your priorities are:';cr. 
priorities do: [:element | Transcript nextPutAll: element; cr]. 
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Giving the Method a Home 

Now that we’ve written our nifty little method, we’d like a place for it to 
live in our IBM Smalltalk image. As we can deduce from the discussion 
in Chapter 2 about how IBM Smalltalk is organized, this is best done by 
creating a new application and adding the prioritize method we just 
created as an instance method in that application. Let’s go do that. 

First, from the System Transcript’s Smalltalk Tools menu, select Manage 
Applications. This brings up the Application Manager window. Now se¬ 
lect the Applications submenu from the Applications menu and then pick 
Create... from the hierarchical menu. Figure 3-7 shows this selection. 

Now we have to give the application a name. We’ll call it Prioritizer. 
This will create a new application and IBM Smalltalk will select this 
newly created application. 

IBM Smalltalk now asks you to declare any prerequisite applications 
(applications that must be loaded in the image for your application to 
run correctly). Our simple application has no prerequisites other than 
the default one, kernel, so just click the OK button and go on. 

From the Application menu again, select Browse Application. This 
opens an Application Browser on the newly created Prioritizer applica¬ 
tion. (Notice that your application already has a class of the same name 
as the application. The connection between these facts will become ob¬ 
vious as you dig more deeply into IBM Smalltalk.) 
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Figure 3-7. 


Creating a new application in the Application Manager 
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We need to tell our newly created class that we are using some of the 
handy constants built into IBM Smalltalk to make our programming easier 
so that it will recognize things like the XmYESNO constant. To do this, 
edit the class definition method that appears in the lower area of the 
browser so that it looks like this: 

Application subclass: //Prioritizer 
instanceVariableNames: ‘’ 
classVar-’ableNames: ‘ ’ 
poolDictionaries: * CwConstants ‘ 

Save the ec.ited class definition (by choosing Save from either the Edit 
menu or the pane pop-up menu, whichever you are used to using). 

Obviously, your new class has no methods yet, so let’s create the lone 
method that will make up its behavior. From the Instance Methods pop¬ 
up menu, choose Template. A template for a new method appears in the 
editing region at the bottom of the browser (see Figure 3-8). 

Open the Workspace in which you’ve been building the prioritize method 
if it isn’t already open. Select all of the text (pressing [ctri]-IXI is the fastest 
way). Copy it. Now select the Application Browser in which the definition 
for the Prioritizer application/class is displayed. Select all of the text in the 
template and paste the previously copied text into the window. 



Template for a new method in the Application Browser 
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Select Save from the pane or Edit menu. You’re done! You’ve defined an 
application class called Prioritizer with a single instance method prioritize. 

Let’s take our shiny new application for a test spin. In a Workspace or 
in the System Transcript, type and execute: 

Prioritizer new prioritize 

Pretty cool, eh? 

Using the Debugger, Part 2 

In Chapter 1 we examined the use of IBM Smalltalk’s Debugger. Since 
you’ll spend more time in the Debugger than you want, we’ll take a deeper 
look at its use here. 

You encounter one of the most trying aspects of IBM Smalltalk pro¬ 
gramming and its Debugger when you generate an error that refers to a 
message you didn’t send in your methods. Trying to sort through such 
bugs can be aggravating, but if you understand that the Debugger is not 
going to help with some kinds of errors, you can save yourself some 
frustration. 

To demonstrate, open a Workspace (you can use the one we created 
earlier in this chapter or a new one) and type in the following code ex¬ 
actly as shown: 

| anotherltem items done | 
items := Set new. 

[done = true] whileFalse: 

[[(anotherltem := CwTextPrompter new 
messagestring: 'Enter something: '; 
prompt)=''] whileFalse: [items add: anotherltem]. 

(CwMessagePrompter 

confirm: 'Finished?' = true) 
ifTrue: [done := true] 
ifFalse: [done := false]]. 


A iterns. 
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You can see that we have simply added a confirmation box to the priori¬ 
tize method code and placed it in an outer whileFalse: loop. If users 
enter a carriage return, we confirm that they want to quit. If they say 
they do not want to quit, we begin again to prompt for additional items. 
Otherwise, we exit and answer the Set of items. 

Select the code and display it. You will see the familiar CwMessage- 
Prompter. Press (Enter) . You encounter an error (see Figure 3-9) that indi¬ 
cates: 

False does not understand asLPSTR 

Where did this come from? We didn’t make any calls to asLPSTR. Heck, 
we don’t even know what an LPSTR is! So how did the IBM Smalltalk 
compiler turn up this error in using our program? 

Step through the stack in the middle-left scrolling list widget. When 
you click on the entry labeled “CwMessagePrompter class»#conf!rm:” 
you should click on the aString variable in the middle list at the top of 
the Debugger. Then look at the next pane to the right. Interesting. Where 
IBM Smalltalk is clearly expecting a string (thank goodness the devel¬ 
oper of this method used a parameter name that told us the type of ob¬ 
ject to expect!], we’re sending a Boolean value (false, without quotation 
marks around it, is not a String object but rather a special logical object). 

This is clearly the source of the problem. Treating a Boolean value as 
a string will get you into trouble every time! 

The problem at this point is that the Debugger doesn’t seem to be of 
much further help. We may have to resort to our own powers of deduction. 

But wait a minute. The code we wrote in the Transcript or Workspace 
that triggered This problem must be in the Debugger somewhere, right? 
See the line in the walkback list that says “UndefmedObject»DoIt?” This 
is where the Debugger displays code that hasn’t been stored as a method 
in a class. Until you connect a method to a class it belongs to the class 
UndefinedObject. Select the line (see Figure 3-9). Note that the currently 
executing line in our method is highlighted. We can be pretty sure the 
problem is caused by a programming error on this line. 
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items := Set new. 

[done = true] whileFaise: 

[[(anotheritem := CwTextPrompter new 
messageString: "Enter something: *; 
pronmpt]= Ba ] whileFaise: [items add: anotheritem]. 
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Figure 3-9. 


UndefinedObject code selected in the Debugger 


The string argument to the confirm: message looks correct, but how would 
the computer interpret it? There are two possible ways you (and there¬ 
fore the computer) could interpret this. It can mean we want to deter¬ 
mine if the string “Finished?” is equal to true (which it obviously is not 
and never will be) or that we want to check the user’s response to the 
CwMessageBox confirm: message. We obviously intended the latter. In 
other words, the computer may be interpreting this code as if it were 
written like this: 

(MessageBox confirm: ('Finished?' = true)) 
when what we really mean is: 

((MessageBox confirm: 'Finished?') = true) 

In technical terms, we have created an order of operations error. The 
equality comparison operation was carried out before the answer from 
CwMessageBox was created and available for comparison. 
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The lower pane in the Debugger is an editor, so you can edit the method 
here and save it. Now try clicking on the Resume button to continue 
executing the method. You won’t be able to do so. Some IBM Smalltalk 
operations can be resumed and others cannot. When you click on Re¬ 
sume, an error dialog box appears. Click OK in that box, select Termi¬ 
nate from the Debugger window’s Processes menu, and close the 
Debugger. Edit the method text as described above, select it, and ex¬ 
ecute it. This time when you press (Enter) or click OK without entering a 
value, things work as expected. 


Incorrect order ol operations is a common problem. Until you become an expert at 
Smalltalk semantics, it may behoove you to use more parentheses than are 
necessary. This can also improve the readability of your code. 







CHAPTER 


In this chapter we will look at high-level programming and design 
issues that make working in Smalltalk easier and more effective. We’ll 
start with a discussion of why object programming “feels” different from 
procedural programming. Then we’ll discuss the “onion peeling” pro¬ 
cess that characterizes all computer programming to some extent and 
see how Smalltalk makes that process more robust and easier to manage. 

The chapter will conclude by examining two main means by which 
we develop applications in IBM Smalltalk: creating objects and add¬ 
ing methods. 

Why Smalltalk Feels Different 

People with a background in other programming languages often expe¬ 
rience disorientation and frustration on their first encounters with the 
Smalltalk environment. “It’s like another planet,” some will say. Or, “I 
just can’t seem to get started.” 

These comments and feelings reflect the fact that object-oriented pro¬ 
gramming is fundamentally different from conventional programming. 
A short example will focus our thinking on the reasons for this. 

Experienced C or Pascal programmers might begin learning a new 
implementation of their favorite language by using the new version to 
write a straightforward piece of code. They might program a favorite 
sorting algorithm to help them learn the new tool and discover some of 
its potential inherent weaknesses. So they write the code and test it. 
What they actually do is to implement the algorithm (the sorting code) 
and pour data into it (the test data that will be sorted). 

If you approach IBM Smalltalk like that, however, you’ll feel like you’re 
on another planet. You can make the transition if you don’t think about 
doing something like pouring data into an algorithm but rather focus on 
a task like creating an inherently sortable object and then giving it the 
ability to sort itself. 

In other words, the emphasis is on a tight integration of data and 
method, not on their separation from one another. 
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Peeling the Onion 

Solving any puzzle resembles peeling an onion. You strip away outer 
layers of information, much of which serves only to distract you from 
your real objective. You penetrate progressively deeper layers until you 
finally reach the core. Along the way, you find useful and some not-so- 
useful parts of the “onion.” 

Programming is puzzle-solving. Regardless of the programming lan¬ 
guage or the program’s purpose, when we’re developing applications 
we are always peeling onions. We begin with an understanding of what 
we want the program to accomplish and with a knowledge of the tools 
available to attain that goal. Then through a series of successive ap¬ 
proximations, we gradually hone our tools and skills as we focus ever 
more intently on the problem. We identify small pieces to deal with and 
master them. (The order in which these processes occur varies, of course, 
depending on our programming methodology. This fact doesn’t make 
the work less like onion-peeling; it just produces more or fewer tears.) 

Object-oriented programming is especially similar to peeling an on¬ 
ion—particularly when working in Smalltalk. We saw in Chapter 2 the 
families of classes and subclasses, sometimes extending five layers deep. 
Associated with each class is a collection of instances and class methods 
together with the code that makes them behave as they do. Finally, at 
the core, there’s the source code, with comments and the source listing 
itself to determine what the method does and how it does it. Sometimes, 
you have to go through all these layers before beginning an IBM Smalltalk 
programming assignment. 

A behavioral or message-passing hierarchy becomes visible beyond this 
organizational hierarchy whenever you try to analyze what is going on in a 
system rather than in a single class. We’ve seen how the Debugger in IBM 
Smalltalk provides a list of currently executing methods. Because applica¬ 
tions reuse existing components, objects you’ve created and objects that 
exist in the IBM Smalltalk class library continually pass messages back and 
forth. Tracking through that maze can sometimes be a challenge. That’s 
why IBM supplies many helpful tools with IBM Smalltalk, including the 
Debugger (which is quite revealing when you know how to use it.) 

Onion-peeling in Smalltalk programming is basically learning how to 
decide when to do what. In this brief chapter we will help you peel the 
IBM Smalltalk onion a little more efficiently. 
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Where to Begin? 

If programming in Smalltalk consists only of creating objects and associ¬ 
ating methods with them, how do you know where to start? How can you 
determine what objects to create? How do you know how to divide up 
methods among all the available objects? In short, how do you know 
what to implement? 

There are, as you might expect, no easy, universal answers to these 
questions. Bin we can offer general guidance that you will find useful 
again and again as you create Smalltalk applications. 

The process of deciding where to begin a Smalltalk programming task 
can be described as posing and answering five basic questions: 


m What do I expect my application to do? (Or, expressed in more 
object-oriented terms, What behavior do I expect my application to 
exhibit?) 

m What objects are needed to represent my application’s components? 
s What is each object’s responsibility? 
m What must each object know about itself? 
h How do objects in my application collaborate with other objects? 

Let’s take a brief look at each of these questions to glean some ideas 
for how to answer them. 


What Should the Applicate Do? 

Obviously, you ’ll have to ask this question regardless of your language 
or methodology. The question is essential to good software design. 

In an OOP system like Smalltalk, the way you phrase the answer to 
this question can be useful. Describe your application’s behavior in an 
English-language sentence. It may take more than one sentence to de¬ 
scribe your application if it is complex. That’s fine. 

When you have refined your sentence description of your application, 
you have gone a long way towards constructing the class diagrams we’ll 
talk about shortly. The nouns in your sentence are candidates for ob¬ 
jects to be created. The verbs are candidates for methods. For example, 
you might write a sentence like this to construct a Smalltalk application 
(like the one we’ll build in Chapter 5) that would enable the user to click 
on buttons to increment or decrement a counter. 



IBM SMALLTALK 


62 


This application consists of a counter that starts out with a value of 
zero and then lets the user change its value by clicking on buttons to 
increment or decrement it by one unit each time. 

This sentence has the following nouns: 

application 

counter 

value 

zero 

user 

buttons 

unit 

time 

Not all of these will be converted to objects, but all the objects we 
create in our application are on this list. 

Similarly, the verbs in the sentence are: 

consist 

start 

let 

change 

click 

increment 

decrement 

Again, not all of these verbs will translate into methods in the finished 
application. But all the methods in that application are either on this list 
or grow out of it together with an understanding of how user interaction 
is implemented in IBM Smalltalk. 

This simple approach will lead you a long way toward a workable 
starting point in designing a Smalltalk application. 

Objects and Their Responsibilities 

Once you’ve listed candidate objects for your application, you must look 
at each object and ask yourself what responsibility it will have in the 
application. 

We know our example will have a counter application object that re¬ 
tains and displays a numeric value, updating the display whenever the 
value changes. So now we can define an object to redisplay the value 
each time it changes. The object obviously needs to know how to add to 
and subtract from the value. 
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Other objects might include buttons that are able to detect when they 
have been the subject of a mouse-click and can send that fact to another 
object. We’ll also need a window of some sort to hold these various objects. 

This simple application maintains a clear line of demarcation among 
objects. This is not always the case. Sometimes you will need to spend 
design time looking for common or similar behaviors among various ob¬ 
jects and combining them into other classes. 

What Do Objects Meed to Know? 

Each object will probably have to maintain information about itself to 
carry out its behavior. The counter object, for example, can’t increment 
or decrement its value unless it always knows the value. Things an ob¬ 
ject must know about itself provide a starting point for a list of instance 
variables to define for the object. 

Sometimes these lists are long, but an object generally needs only a 
few pieces of information about itself to behave as expected. 

How Do Objects Collaborate? 

You don’t build Smalltalk applications in a vacuum. The holistic nature 
of the application is a key difference between programming in an OOP 
environment like Smalltalk and developing programs in more traditional 
systems and languages. Objects interact with other objects in the system 
even when the interaction is not obvious. 

Any time you use a system method, subclass an existing IBM Smalltalk 
class, use a menu, create a window, or engage in other activities charac¬ 
teristic of the IBM Smalltalk system, you use classes and objects that you 
did not create and of which you may be unaware. 

When you create a run-time version of your application, you need to 
be especially aware of these interactions and collaborations to be suc¬ 
cessful in completing your application because a run-time application 
contains only a subset of the class library. 
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Starting with Class Diagrams 

Programming in IBM Smalltalk becomes much easier when you approach it 
systematically. Our favorite method for doing this is to use a class diagram. 



David A. Wilson invented class diagrams and used them for several years in 
teaching OOP before writing an article, "Class Diagrams: A Tool for Design, 
Documentation, and Testing" in the January/February 1990 issue of the Journal of 
Object-Oriented Programming. 


A class diagram defines a class name, instance variables associated 
with the class, and the methods or behaviors the class must have. (See 
Figure 4-1 for a sample.) 

You can more readily create and modify the diagram if you first think 
about the problem to be solved. Attempt to create a written or oral de¬ 
scription of the problem. When you have done so, identify the nouns in 
your sentences that describe the problem. As we’ve said previously, these 
nouns are candidates for objects. Now identify all the verbs; once again, 
these are candidates for methods. 
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This approach will not identify every element needed in every appli¬ 
cation. Experiment with the technique and modify it for yourself. It will 
help you make a usable start on the design process. 

When you’ve created a rectangle in the class diagram for each object 
identified, you’re ready to start finding common behaviors and creating 
a class or class hierarchy to support these common threads. If you’ve 
created more than one object that seems to be able to do the same thing 
(even if using different algorithms), group them together. Consider giv¬ 
ing them a common ancestry by creating an abstract class (a process 
we’ll discuss shortly). 

Miif Objects 

As we’ve said, Smalltalk programming consists of extending an existing 
Smalltalk class library by creating new classes and adding methods to 
these classes. 

When refining the behavior of a class or extending its capabilities, or 
when adding to its knowledge of itself (by creating instance variables), 
you may find it appropriate to create a new class. When creating a new 
class, the first thing you have to do is decide which class to subclass, since 
all new classes you create must be subclasses of some Smalltalk class. 

Subclassing the Class Object 

Your first impulse will be to define your new class as a subclass of the 
top IBM Smalltalk class, Object. Every class in the IBM Smalltalk class 
library is a descendent of Object, and since every class must have a 
parent, or superclass , using Object is the easiest thing to do. 

Classes created as subclasses of Object inherit a good bit of fairly 
generic behavior. Most instance methods of the class Object relate to 
object management (see Table 4-1) or provide basic, generic behavior 
that your objects will usually override or supplement. (Don’t worry if 
terms and concepts in the table are unfamiliar to you; we will discuss 
them throughout the book where they are appropriate.) We’ve identified 
in Table 4-1 the application where the method is originally defined. 

Other behavior associated with the class Object involves such activi¬ 
ties as printing or displaying the object’s value, providing support for the 
dependency mechanism (see Chapter 5), and forcing the sending of mes¬ 
sages to the object. 
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Table 4-1. Object-Management Methods of Class Objects 


1 METHOD 

APPLICATION 

PURPOSE \ 

addDependent: 

CLDT 

Create new dependent of object. 

allReferences 

CUM 

List all references to an object. 

become: 

CLDT 

Convert an object's type. 

broadcast 

CLDT 

Notify all dependents of argument or change. 

class 

CLDT 

Identify the receivers class. 

copy 

CLDT 

Copy the receiver. 

deepCopy 

CLDT 

Copy the receiver and make copies of all in¬ 
stance variables. 

dependents 

CLDT 

Identify all objects that are defined as depen¬ 
dents of the receiver. 

doesNotUnderstand: 

CLDT 

Used in error handling 

error: 

Core 

Used in error handling 

halt 

Core 

Force a Debugger to appear from within a 
method. 

halt: 

Core 

A variation that lets you supply a string for 
tracking which of several halt messages is be¬ 
ing invoked. 

ifNil: 

AbtCLDTAdditions 

Determines if an object's value is Nil. 

ifNotNil: 

AbtCLDTAdditions 

Determines if an object has a non-nil value. 

inspect 

EtBaseTools 

Open an inspector on the receiver. 

isKindOf: 

CLDT 

Test whether the receiver is an instance of a 
particular class or any of its subclasses. 

isMemberOf: 

CLDT 

Test whether the receiver is an instance of a 
particular class. 

isNII 

CLDT 

Test whether the receiver is nil. 

notNil 

CLDT 

Test whether the receiver has a value other 

than nil. 

printOn: 

CLDT 

Print default information and a representation 
of the receiver on a stream. 

release 

CLDT 

Disconnectall dependents ofthe receiverfrom 

the receiver. 

removeDependent: 

CLDT 

Disconnect a specific dependent of the re¬ 
ceiver from the receiver. 

respondsTo: 

CLDT 

Determine if the receiver has a method to re¬ 
spond to the argument message or inherits 
such a method from an ancestor. 

shallowCopy 

CLDT 

Copy the receiver without copying its instance 

variables. 
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shouldNotlmplem ent 

CLDT 

Initiate a Debugger because a subclass doesn't 
implement a method that it should implement. 

size 

CLDT 

Answer the size of the receiver. 

species 

CLDT 

Return a class that is similar to (or the same 
as) the receiver. 

yourself 

CLDT 

Answer the receiver. 


Subclassing Other Classes 

If you find a class in the IBM Smalltalk class library that exhibits some of 
the behavior you desire, you can create a subclass of that class rather 
than of Object. This, of course, means that the newly created subclass 
inherits all of the behavior of the class you’ve chosen and all of its super¬ 
classes, including Object. 

For example, to create a new class to deal with a new type of aggre¬ 
gate of elements (such as a new dictionary with a special capability), you 
would probably look first to the class Collection or one of its subclasses 
to see which one seems to offer greatest support for the behavior you 
wish the object to exhibit. Having identified such a class, you can create 
your own subclass of it using the process outlined below. 

The Subclassing Process 

In IBM Smalltalk, subclassing may optionally involve application man¬ 
agement activities that we’ll cover later in the book. For the purposes of 
this discussion, assume that you have identified or created the correct 
application in which to define your new class as part of your analysis 
leading to the point where you are ready to create your subclass. 

The step-by sfep process for creating a subclass of an existing IBM 
Smalltalk class is quite simple, whether it involves a class that came 
with the IBM Smalltalk library or one you added: 

1. In a browser, use the class list pane pop-up menu to find the class you 
wish to subclass and select it. (This step is actually optional, as ex¬ 
plained in the note below.) 

2. From the class list pane pop-up menu, choose Template Subclass. 

3. Edit the template of the class definition that appears (see Figure 4-2). 
You will have to provide the name of the new class and the name of the 
class you wish to subclass to create the new class at a minimum. 

4. Select Save from the text editing pane pop-up menu. 
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The template for the new class definition in a browser 


The new class is now selected and ready for your first method, follow¬ 
ing the steps outlined in the preceding discussion. From this point on, 
the new subclass is treated like any other class in the library. 



pop-up menu. You will then be given a chance to define the new class interactively, 
including identifying the application to which it should belong. You should experiment 
with both approaches and adopt the one that seems to you most efficient 


Modifying Behavior of a Chosen Class 

Subclasses override one or more pieces of inherited behavior (which is 
why subclasses are created). To make subclassing accessible, you must 
understand how to select and modify methods. These methods will fall 
into three categories: those you should ignore, those you should con¬ 
sider modifying, and those you should replace (or override) completely: 
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m Ignore methods unrelated to the functionality you are adding to the 
system via your new subclass and that need not deal with instance 
variables introduced by the subclass. 
m Extend methods that are useful but that need supplemental behav¬ 
ior, perhaps because of new instance variables introduced by the 
subclass. 

■ Replace methods whose names and behavior you wish to use but 
whose implementation is not appropriate for your class. 


Methods that fall into the second category are dealt with by the simple 
expedient of defining a method of the same name in your subclass, car¬ 
rying out the supplemental activities, and then sending the message to 
the superclass version of the method with a line like this (assuming the 
method you’re overriding is called doMethod ): 

... your new code . . . 

A super doMethod 

This line simpl3' tells IBM Smalltalk, “Use the doMethod method found in 
the superclass of the receiver.” In other words, IBM Smalltalk will carry 
out your special processing and then use the inherited version. It is pos¬ 
sible, of course, to execute the superclass method first and then carry 
out the specialized processing in your method of the same name. But 
you must understand the implications of this approach. Including such 
code ensures a consistent return value but may in some circumstances 
entirely undo the work you designed your method to accomplish. As a 
rule, be sure to return a consistent value in keeping with the inherited 
version of the method you are overriding. 

If the behavior embodied in the method in the superclass is not ap¬ 
propriate to the new class you’re defining, define a new method to over¬ 
ride the behavior exhibited by the ancestor class or classes. This ap¬ 
proach includes disabling behavior completely. If you simply do not want 
your objects to respond to a message in the superclass, you can’t just 
ignore it in the superclass. Instead, you must define a method that does 
nothing (or something invisible) and give it the same name as the method 
you wish your class to ignore. Note that if you find yourself with a great 
many of these methods, you should rethink your design. You may not 
have chosen the best class to subclass for your project. 
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Creating and Using Abstract Classes 

An “abstract” class in Smalltalk is a class that is not intended to have 
instances. It exists for the sole purpose of grouping together related be¬ 
haviors that will be exhibited by objects created from its “concrete” sub¬ 
classes. But that definition is a bit too abstract, so let’s take a look at a 
specific example. 

The class Collection is an abstract class. You would never create a 
new object and call it an instance of Collection. 

An abstract class is a repository for behavior shared by all instances 
of all its subclasses. Collection, for example, defines behavior that all 
collections need to know how to do, including such things as: 

m Adding, deleting, and retrieving elements of the collection 

m Iterating over all of the members of a collection, executing a block of 
code for each element 

■ Displaying or printing itself in some useful way 

Many of these methods as defined in the abstract class Collection do 
nothing, or else they return an error indicating that the method should 
be implemented by a subclass. For example, the method add: in the 
abstract class Collection might do nothing but send the message 
implementedBySubclass to the receiver (self) and return the result. In 
other words, the add: method is so specific to the type of collection that 
we cannot generically implement behavior that will apply to all types of 
collections. (Of course, many methods in abstract classes do implement 
real behavior.) 

The Purpose of Do-Nothing Methods 

You may be tempted to ask, “If these methods don’t do anything or, worse 
yet, generate errors if not implemented in my subclasses, then why are 
they defined at all?” The answer relates to the general purpose for which 
abstract classes exist. We’ve said that abstract classes exist only to gather 
behavior that is common to all their subclasses. Another way of saying 
this is that abstract classes define “policies” (that is, what all subclasses 
and their instances must know how to do if they are going to be members in 
good standing of the abstract class), whereas concrete classes (those 
that are not abstract) define the “mechanism” for carrying out a policy. 
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Seen in this light, the add: method in the class Collection tells you as 
a IBM Smalltalk designer that if you create a new subclass of this class, 
you must be sure that it knows how to respond to the add: message. It 
sets a policy: all members of this class know how to deal with the mes¬ 
sage add:. It is up to your class to implement this method as it wants 
(including, of course, ignoring it by defining an add: method that does 
nothing). But you cannot ignore it without generating a walkback. 

Identifying the Right Class 

A difficult part of programming in Smalltalk is identifying the class to 
subclass—whether that class is abstract or concrete. How do you go 
about this? 

There are no hard and fast answers. This part of Smalltalk program¬ 
ming lends itself to many stylistic differences among programmers. We 
know Smalltalk developers who apply the following techniques: 

n Examine abstract classes for desired behavior, then critically ana¬ 
lyze a candidate abstract class’s subclasses. 

m Create a. subclass of Object and, after implementing some of the ap¬ 
plication, move it as appropriate. 

n Ask other programmers in their group or circle of colleagues. 

Ultimately, there is no substitute for a solid working knowledge of 
what’s in the IBM Smalltalk class library. This book will familiarize you 
with the most useful and important elements of the class library in order 
to provide a base from which to begin your own explorations. 

You will rarely find a class coded with all the behavior you want. (When 
this does happen, it certainly makes your job easy!) Look for a class with 
a reasonable amount of behavior dealing with things you expect your 
class to understand. When you find such a class, dig in and start pro¬ 
gramming. If your search doesn’t yield perfect results, you can build 
your own class and later make it a subclass of a class you identify as 
useful. 

In Chapter 5, we’ll take a close look at a practical example of how to 
approach this problem. 
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Adding Methods 

The simplest approach to programming in Smalltalk is to find a class 
that makes a good “home” for the behavior you’re trying to add to the 
system and simply define a new method for that class. 



When you define methods in IBIV1 Smalltalk, you may optionally wish to assign them 
to a category. IBM Smalltalk doesn't force you to do this and treats any method you 
define without a category as a member of a special category called "Uncate¬ 
gorized." But you'll find as you work with IBM Smalltalk that the availability of 
categories is quite helpful in bringing order out of the massive size and complexity 
of the class library. As a general rule, we do not refer to categories in this book. We 
assume you use the instance methods or class methods to view methods. 


This process is the easiest because: 

m Adding a new method does not require you to know very much about 
the class involved and its overall behavior. In fact, you could grab an 
arbitrary class and stick a new stand-alone method (one that didn’t 
depend on that object’s other behaviors) into it. This would not be 
good programming practice, but it illustrates the point that you need 
not always have an in-depth understanding of a class before adding 
a new method to it. 

m Adding a new method is a relatively simple process. We’ll provide a 
step-by-step instruction list shortly, just for reference. 

■ Adding a new method is easy to undo. You can use it to experiment 
with a new method approach without committing yourself to careful 
tracking of potential changes to the image. 
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The Process of Adding a Method 

Here is the process of programming in IBM Smalltalk by adding a method 
to an existing class: 

1. Identify the class to which the new method should be added. Ideally, 
the class will contain related functionality and occupy a “good” posi¬ 
tion in t he hierarchy (that is, its subclasses will make good use of the 
method as well). 

2. If you are in a class list, find the class in the browser and move to (or 
open) an instance or class method pane. Otherwise, you must first 
select the Classes Application. 

3. In the method list pane, choose Template from the pop-up menu. 

4. Enter the source code for the new method in the text-editing pane— 
generally by editing the template IBM Smalltalk provides. But you 
may occasionally type the method code into the Transcript or a 
Workspace window, or you may copy a similar method from a differ¬ 
ent class in the CHB. In that case, simply copy it from that window, 
select the entire method template in the text-editing window of the 
CHB, and paste the copied method over the template. 

5. Select Save from the text-editing pane’s pop-up menu. 

That’s all there is to adding a method to a class. Your new method 
can now be invoked by sending a message to the class or an instance 
of the class. 

Avoid Adding Methods to System Classes 

Adding a method to an existing class is so straightforward you might 
wonder why we don’t handle all IBM Smalltalk programming this way. 

When adding a new method similar to one that already exists, select the 
existing method, edit its name to the new method name, and then edit and 
save the code. When we made our first pass at implementing the prioritize 
method in Chapter 3, for example, we simply added it to a class. This addi¬ 
tion did not significantly affect other objects in those classes but only al¬ 
tered their menus (a relatively nonintrusive change). Similarly, it did not 
depend heavily on those classes and their other methods. 
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Create a new method by adding a method to an existing class only if 
the new method will be added in just one place. If a new method needs 
to be added in several places, perhaps it is being inserted at the wrong 
position in the class hierarchy. 

Finally, try to avoid adding methods to existing classes if your design 
requires you to add several new methods to one or more existing classes. 
That situation probably indicates you’ll be able to build a more special¬ 
ized object, so create a new class to hold all related pieces of behavior. 
This is not, however, to say you should never build an application by 
adding many methods throughout the system. But it isn’t often the right 
technique from the standpoint of reusability. 

In other words, before you create new functionality for your Smalltalk 
environment by adding a new method to an existing class, be sure it is 
singular and isolatable. If so, you’re probably safe handling the task by 
adding a method. Otherwise, use another technique. 



CHAPTER 



A Simple Counter 


In our first project, the Prioritizer, which appeared in Chapter 3, our 
primary programming technique was adding methods to existing classes. 
At the conclusion of that process we saw how to create a new class with 
a single method and then use that class just as though it were supplied 
in the class library. IBM Smalltalk applications usually consist of more 
than one class with a single method. 

This chapter extends our work with IBM Smalltalk as we build an¬ 
other application. This time we begin by creating a new class. We delib¬ 
erately keep the application small in order to concentrate on details of 
design and programming techniques common to all IBM Smalltalk pro¬ 
gramming projects rather than spend a lot of time on details unique to 
the operation of the specific application. Although the project is small, it 
is functional and forms the kernel of something that could be useful. 

Project Overview 

This project involves creating a counter. In Chapter 4 we described this 
project in a single sentence that served as the starting point for our 
design. We said the project would consist of a counter that starts with a 
value of zero, then allows the user to change its value by clicking on 
buttons, each click incrementing or decrementing the number by 1. We 
will also toss in a button to reset the value of the counter to zero on 
demand. Figure 5-1 is a sketch of the finished application. When the 
user clicks on the button labeled Increment, the counter increases the 
value by 1. If the user clicks on the decrement button, the counter de¬ 
creases the value by 1. 

That’s all there is to the project. Let’s see how we might design it. 
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Counter Example 




Figure 5-1. 


A sketch of the counter project 


A Quick Overview of the User Interface Classes 

An interactive Smalltalk application consists of instances of CwWidget 
subclasses or one of its subclasses. The primary types of objects involved 
in the user interface are: 

a Desktop windows called shells (rectangular areas on the screen 
each with a title bar, a menu, and any of several standard Win¬ 
dows controls), which are typically instances of the class CwShell 
or one of its subclasses 

b Component objects (which generally display information and pro¬ 
vide interaction points for the user) 


What follows is a brief discussion of CwWidget, the CwShell subclass 
CwTopLevelShell, and two CwWidget subclass objects: CwPushButton 
and CwLabel. In the course of our discussion we will also deal with the 
CwWidget subclasses CwRowColumn, CwMainWindow, and CwForm, 
which form the framework on which we will hang our application ob¬ 
jects. Our purpose here is simply to convey enough information for you 
to understand the program example in this chapter. Chapters 8-11 will 
provide opportunities to delve more deeply into the details of windows 
and their related objects. 

CwWidget (Common Widgets) 

All visible elements of IBM Smalltalk, with the exception of drawn graph¬ 
ics, are instances of subclasses of CwWidget, and are collectively re¬ 
ferred to as common widgets, or widgets for short. Even windows are 
instances of the CwWMShell class or one of its subclasses, and the 




CHAPTER 5: A SIMPLE COUNTER 


77 


CwWMShell class is a subclass of CwShell, which in turn is a subclass of 
CwBasicWidget, which is a subclass of CwWidget. 

Widgets are based on the OSF/Motif Window model, part of the OSF 
implementation of UNIX. The Common Widgets subsystem is provided 
by IBM Smalltalk to enhance application portability. Using common wid¬ 
gets, you can create a completely portable windowing environment. In 
fact, we were able to move our applications freely back and forth be¬ 
tween OS/2 end Windows while writing this book. 

Widgets can have zero, one, or more child widgets attached depend¬ 
ing on the type of parent widget. There are three basic types of widgets, 
which are defined as CwWidget subclasses CwPrimitive, CwComposite, 
and CwShell. They are defined as follows: 

m CwPrimitive widgets do not have child widgets; they define ob¬ 
jects such as buttons, lists, and labels. 

h CwComposite widgets can have zero or more children; they rep¬ 
resent collective window objects such as frames and scrollable 
windows. 

h CwShell widgets have only one child; they manage the interface be¬ 
tween the application and the host window manager. The shell also 
displays the title bar and any host-specific buttons or decorations. 


The Widget Tree 

Widgets are collected into a top-down structure called a widget tree. At 
the top of the tree is the shell widget (we will use the class 
CwTopLevelShell), which contains one child widget, CwMainWindow. 
These widgets define the window itself, including its title, host-specific 
buttons and decorations, the frame, menu bars, and the work area. To 
this window we add the primitive widgets we need for our specific appli¬ 
cation, namely the buttons and label field. 

Before we can hang our primitive widgets on the tree, we need some 
branches to hang them from. We add branches to the tree with compos¬ 
ite widgets. You can think of the primitive widgets as the ornaments that 
are hung from the branches. The branches not only hold the ornaments 
but also determine how the ornaments are laid out next to each other. 
Some commonly used branches, or composite widgets, are CwForm and 
CwRowColumn, which we will discuss in more detail later. The tree is 
completed by hanging the primitive widgets, or ornaments, on the com- 
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posite widgets. All the code that is required to create a widget tree is 
generally found or referenced in an open method. 

Designing the Project 

Ours is a single-window application. The window consists of four com¬ 
ponents: 

m A button for incrementing the counter’s value 
■ A button for decrementing the counter’s value 
m A button for resetting the counter’s value to zero 
m A place to display the current value of the counter 


Defining the Class 

We begin, as promised, by defining a new class with which to associate the 
behavior and the application. Generally speaking, we do this in four steps: 

1. Open an applications browser. 

2. Create an application. 

3. Select the prerequisites for the application. 

4. Create a class for the application. 

5. Create and define the primary attributes of the new subclass. 


Let’s follow these steps for this sample application. 

(Ming a lew Application 

Applications are, in the simplest case, named units of storage for saving, 
loading, and managing the collection of classes. They make up an IBM 
Smalltalk application as a whole. Browsing an application allows you to 
focus on only the classes that will be modified or defined by an application 
and not the entire set of Smalltalk classes. Applications can be thought of as 
libraries of classes. Applications make it easy to load, save, and manage a 
large number of classes, and they allow you to manipulate classes as a 
single named entity. The IBM Smalltalk environment includes a substantial 
number of applications including several example applications. 
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As a rule, the first step in building an IBM Smalltalk application is to 
define a new application to contain all of the code related to the applica¬ 
tion. The first step in creating an application, then, should be to select 
the appropriate application as the default. If an appropriate application 
doesn’t exist, you’ll have to create that as well. Fortunately, IBM pro¬ 
vides an applications browser for this purpose. 

IBM has anticipated the need to create new applications and their 
associated classes. From the Transcript Smalltalk Tools menu, choose 
Browse Applications. The browser shown in Figure 5-2 appears. 

To be sure we are in sync, set the TrailBlazer options to these: 


m Default Private Methods Filter 
m Enable Method Categories 
m Default Method Inheritance 
m Show Classes Hierarchically 
■ Show Public/Private Buttons 


off 

off 

No Inheritance 
on 

off for both 


Close the current browser and reopen a new one, which will reflect the 
new settings. You should now be able to follow along step by step. (If you 
choose not to save your image, you will need to set these options again 
before continuing). 
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Figure 5-2. 


The apipJications browser—TrailBlazer 
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Loaded Applications -TrailBlazer 
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Figure 5-3. 


The applications browser with new Counter application 


In the list labeled Loaded Applications, click the right mouse button for 
the pop-up menu. From this menu, choose Create and then Application... 
from the submenu. Name the project “Counter” and then click the OK but¬ 
ton. Figure 5-3 shows the browser after adding the Counter application. 

We now need to add the application prerequisites. We can do this with 
the two lists at the bottom of the browser window. Select the application 
Common Widgets from the list labeled Available and move it into the Cur¬ 
rent Prerequisites list using the »> button. Prerequisites are applications 
whose classes you expect to use in your application. Prerequisites can be 
nested. When you assign a prerequisite, you are also assigning that 
prerequisite’s own prerequisites. The selected application should now be 
Counter, and in the list labeled Classes you will see the following: 


Object 

SubApplication 

Application 

Counter 

Select the class Object and right mouse-click, and then select first 
Add and then Subclass of Selected Class from the submenu. Enter the 
name “CounterWindow” and click OK. The subclass list will be displayed. 
Choose Subclass and click OK. 

As you can see, we have created two classes: Counter and Counter- 
Window. In the applications browser, click on the CounterWindow class. 
The lower pane of the Browser window changes from the prerequisites 
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lists to the source display. We can see the default class definition for 
CounterWindow. 

Click on the class Object and look at the Instance Methods list. Notice 
there aren’t any methods in the list. “Hold on here, this can’t be right,” 
you say, “Object should have many instance methods.” But wait, we are 
viewing the class through the applications browser, and the applications 
browser displays only methods that have been added to the application. 
Since we have not added any Object instance methods to the applica¬ 
tion, none are displayed. 

The applications browser sets the scope of our view to only the classes 
and methods that are new or changed. IBM Smalltalk refers to new and 
changed classes as defined and extended, respectively. 

To see the Object class outside of the applications browser’s scope, 
select Loaded Classes from the Loaded Application drop-down list. Al¬ 
ternatively, you can choose In Application then All Applications from the 
Method List pop-up menu. Now we have a different view of the image. 
Our scope is all of the IBM Smalltalk classes. When you click on a class, 
your view is no longer restricted; you see all the methods defined for the 
class regardless of whether they are part of the application. 

You can easily switch the scope of the browser by switching between 
Loaded Applications and Loaded Classes. The Transcript Browse menu 
has options for both Applications and Classes that open new browsers 
set to Loaded Applications and Loaded Classes respectively. 

Defining the Window Class 

Return the browser to the Loaded Applications list view and click on the 
Counter application. Next, click on CounterWindow in the Cla-ses list to 
bring up the class definition in the lower section of the window: 

Object subclass: #CounterWirtdow 
instanceVariableNames: ' 1 
classVa riableNames: '' 
poolDictionaries: '' 

We obviously need to extend the definition to include our instance 
variables and constants. We will store the value of our counter in an 
instance variable called value. We also need to access constants that are 
common to the common widgets architecture and are stored in the pool 
dictionary CwConstants, so we will define this as a pool dictionary for 
the class. Here is the changed code: 
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Object subclass: #CounterWindow 
instanceVariableNames: 'value' 
classVariableNames: 
poolDictionaries: 'CwConstants' 

Add the changes to the definition in the browser and then save it by 
selecting Save. We do not need to change the Application subclass 
Counter. In fact, as a rule of thumb, you should never change the Appli¬ 
cation subclass definition. 

initializing the Application 

While we are here and before we forget, let’s initialize the value in¬ 
stance variable. This step will make it easier for our buttons to compute 
the value without having to determine if the instance variable is a num¬ 
ber. We will do this by adding a class method called new that overrides 
the default new method. 

The first step is to select Class Methods from the drop-down list above 
the Instance Methods list. Then in the resulting list, select Template. 
Replace the template with: 

new 

''answer a new counter'' 

A super new initialize 

As with most methods which override a superclass method, we start 
by first calling the superclass method, using the pseudovariable super. 
This call results in the creation of a new object. Next we send the result¬ 
ing object, which is an instance of CounterWindow, the instance method 
initialize, which we will create next. The method answers the newly 
created and initialized object. The caret before this line of code is very 
important. Without it the method would answer the default object self, 
in this case the CounterWindow class, not an instance of the class. Switch 
back to the instance methods by selecting Instance Methods from the 
drop-down list. Then, from the pop-up menu, select Template. We are 
now ready to add the instance method initialize. Here is the one-line 
method: 

initialize 

’ 'initialize the counter to 0'' 
value := 0. 
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Defining the Window 

Now we are ready to define onr widget tree for this application. We will 
do this by creating a new instance method for the CoimterWindow class 
called open. This will ultimately be a very long and somewhat compli¬ 
cated method, so we will build it one piece at a time. From time to time 
we will test it to see how things look. 

Let’s first create the open method. Right mouse-click in the Instance 
Methods list and select Template. Change the pattern to the following: 

open 

''open a Counter'' 

| shell ma'n form text rowColumn buttonl button2 button3 | 

Now save the method, first making sure that you remove the line with 
the word “statements.” 

The first part of our tree, as you’ll recall from our earlier discussion, 
is the shell widget. For our purposes, we will use the CwTopLevelShell 
class. This will create a standard nonmodal window with a title bar. To 
this we will add the composite widget CwMainWindow, which adds the 
main branch that all other widgets will branch from. 

Here is the open method with the code necessary to add these widgets: 

open 

''open a Counter ' ' 

| shell main form text rowColumn buttonl button2 button3 | 

shell := CwTopLevelShell 
createAppl i cati onShel 1 : 'Counter Example' 
a rgB1 ock : nil. 
main := shell 
createMainWindow: 'main' 
argBlock: nil. 
main manageChild. 
shell realizeWidget. 

Save this method as it is. We will hold off discussing the individual 
methods used in this method until Chapter 7. For now it is sufficient to 
say the code defines a Shell Window and a Main Window, and the last 
line of the code displays the window. 
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You may be wondering if you can run this code the way it is now. In 
fact, you can; the result won’t be very satisfying, however. You’ll get a 
small window wide enough to display the title bar. Still, if your curiosity 
just got the better of you, type the following in an empty workspace or 
the Transcript: 

CounterWindow new open 

Select the text and execute the code by selecting Execute. 

Adding Brandies 

The next step is to create the branches on which to hang the primitive 
widgets. What we need here is one branch on which we can hang the 
others. This branch is called a form and is defined by the class CwForm. 
The form is a composite widget that provides positioning management 
for all widgets attached to it. You can attach to it other composite wid¬ 
gets, or to primitive widgets. 

For our purposes we will attach to the form a special composite wid¬ 
get called a CwRowColumn. This widget has the unique property of align¬ 
ing widgets it contains into rows or columns. We’d have killed for such 
an ability in other Smalltalk dialects. We will hang our three buttons on 
this widget. 

Here is the open method with the new code added: 

open 

''open a Counter ' ' 

| shell main form text rowColumn buttonl button2 button3 | 

shell := CwTopLevelShel1 
createApplicationShel1: 'Counter Example' 
argB1ock: nil. 
main := shell 
createMainWindow: 'main' 
argBlock: nil. 
main manageChi 1 d. 

form := main 

createForm: 'form' 
argBlock: nil. 
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form manageChJId. 

rowColumn := form 

createRowColumn• 'buttons' 
a rgB1ock : [ : w | w 
numCol limns : 1; 
orientat"on: XmVERTICAL; 
packing: XmPACKCOLUMN]. 
rowColumn manageChild. 
shell real i z e // i d g e t. 

If you look closely at the code, you can see how the widgets are laid 
out. A message to a previous layer widget is called to create the new 
widget. The code following the argBlock: in the rowColumn widget cre¬ 
ation section sets the alignment for this widget’s child widgets. 

Another Test? 

What do you think? Should we check the window and see what it 
looks like now 9 Or do you think the above code had no visible effect? To 
make testing the application easier, we will create a class method in the 
Counter class called example. 

example 

"open a new counter" 

CounterWindow new open 

Now we really have something we can test. To test our application, 
enter a workspace, or the Transcript Counter example, select it, and 
execute it. 

Not very exciting. It’s a little larger, but not much is going on. Still, it’s 
nice to know it did not crash. 

The open method is starting to get long, so from now on we will only 
display the code changes for the method. Remember that all code changes, 
unless otherwise specified, will be added immediately prior to the “shell 
realizeWidgets” statement. 

Remember to set yourself back to instance methods and to select the 
CounterWindow class before continuing this chapter. 
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Attaching the Branches 

One of the reasons our window test was less than spectacular is that we 
have not defined how the widgets are to be attached. This is where the 
tree analogy breaks down. Branches have only a single point of connec¬ 
tion (unless of course they are Banyan trees), while widgets, because 
they are rectangular in nature, can connect on all four sides. 

What a widget needs to know is not location, but how it attaches to 
other widgets. Much of the drudgery normally associated with sizing 
and positioning windows and their components is eliminated with this 
style of geometry management. 

You may have noticed that each piece of widget creation code ends by 
sending the message manageChild to the widget. This message is sent to 
a widget to tell it that it is to participate in geometry management, which 
means that its size and position will be managed by its parent. 

Once a widget has declared it is managed, it must declare its attach¬ 
ments. In most cases the attachments default to the containing parent 
widget. However, there are times, such as this one, when you want to 
control how much form each widget occupies. This task is accomplished 
by sending a series of attach messages to the child. Let’s look at the code 
for the rowColiimn widget: 

rowColumn setValuesBlock: [:w | w 
topAttachment: XmATTACHFORM; 
topOffset: 2; 

bottomAttachment: XmATTACFIFORM; 
bottomOffset: 2; 

1 eftAttachment: XmATTACFIFORM; 
leftOffset; 2]. 

What this code says is that the child, rowColumn, is attached to the 
form on all but the right side. Notice that we have also added some off¬ 
sets from the sides of the form so that spacing will not change. You can 
add this code prior to the “shell realizeWidget” statement but after 
“rowColumn manageChild.” The XmATTACHFORM value is a constant 
taken from the CwConstants pool. Don’t worry about its significance now. 
We’ll discuss this in the next section. 
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Adding Components 

We are now ready to add some ornaments to the tree. Let’s start with the 
Add button. From what we learn there, we should be able to figure out 
how to place the other three elements fairly easily. 

The buttons will all be instances of the class CwPushButton. Each 
button will have to know three things: its label, its location (relative to 
the widgets around it), and what method to execute when the user clicks 
on it. We’ll deal with this last issue in the next section. For now, let’s get 
the window designed. 

We will need to create a new CwPushButton object. Fortunately, we 
have some methods predefined for this purpose. We send the 
createPushButtori: method to the rowColumn widget, the parent of our 
buttons. The argument to this method is used as the label of the button. 

The location should be easy since, according to the widget tree scheme, 
the parent should manage that one for us. Let’s see if this is indeed true. 
Add and save the following code immediately before “shell realizeWidget.” 

buttonl := rowColumn 

createPushButton: 'Add' 
argB1ock: nil. 
buttonl manageChi1d. 

Good thing we added lots of temporary variables. As you may have 
suspected, we will use them all up. This code is as advertised; it simply 
creates a push-button widget named “Add.” Now test it. At last, a nor¬ 
mal looking window. It should look like the one in the illustration below: 



As you can see, the button location and size were handled automati¬ 
cally for us. Let’s add the other two buttons and see what we have. Here 
is the code to be added. The easy way to enter this code is to copy the 
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existing button code and paste it twice, and then to change the button 
labels and temporary variable names. Don’t forget the second use of 
each variable before “manageChild”: 

button2 := rowColumn 

createPushButton: 'Subtract' 
argBlock: nil. 

button2 manageChild. 

button3 := rowColumn 

createPushButton: 'Reset' 
argBlock: nil. 

button3 manageChild. 

Test the application. Wow! That’s amazing, isn’t it? Perfectly lined up 
on the first try. That sure saves a lot of time. Now you can see why we 
used the rowColumn widget. 

The only widget left to add is the label widget that will display the 
current counter value. This widget will be hung directly on the form 
branch and positioned to the right of the rowColumn widget. Let’s look 
first at the creation of the widget. Here is the code: 

text : = form 

createLabel: ' text' 

argBlock: [:w | w width: 180; height: 170; borderWidth: 1]. 
text 1abelString: 'O'. 

text manageChild. 

There are a couple of things to point out here. First, we control the 
size of the widget by explicitly stating its width and height. Second, the 
argument for borderWidth is either 1 or 0. 1 turns on the border, 0 turns 
it off. And finally, unlike a button, we have to set the label’s string explicitly. 

Add the code to the open method, save it, and test the application. 
What is this? Our other two buttons have gone away. Try resizing the 
window. Notice that the label area overwrites the buttons in the 
rowColumn area. When you widen the window, you can even see the 
edge of the label area. This is a demonstration of how an unattached 
widget behaves, or more accurately, misbehaves. 

Let’s attach the widget and see if it is better behaved. Here is the code 
for attachment, which you should insert in the usual place: 
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text setVa1uesBlock: [:w| w 

bottomAttachment: XmATTACHFORM; 
bottomOffset: 4; 
topAttachment: XmATTACHFORM; 
topOffset: 2; 

rightAttachment: XmATTACHFORM; 
rightOffset: 4; 

1eftAttachment: XmATTACHWIDGET; 
leftWidget: rowColumn; 
leftOffset: 5]. 

Besides the offset size, this code looks like the attach code for the 
rowColumn widget, right? 

No, not quite. Look closely at the leftAttachment code. It is using the 
constant XmA TTACHWIDGET instead of XmATTACHFORM. Sending this 
constant as an argument tells the parent that the widget is to be at¬ 
tached to another widget, not to the form. The next line indicates which 
widget this widget should attach to and to which side. 

Add the code to the open method, save it, and test it. The results should 
be the same in the illustration below: 




The first thing you will notice is that all the buttons are back. Now try 
resizing the window. 

Our window is complete. Or is it? If you click on the buttons, you will 
see that they highlight. Nothing else happens, of course, because we 
don’t have any code “wired up” yet. As you may have guessed, we still 
have some work to do, which we’ll tackle in a later section. 

Our open method contains all the code for creating the application’s 
widget tree and is only the second instance method we have written so 
far for the CoimterWindow class. 
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While we have been creating this long method, we’ve learned how to 
build a widget tree by adding and attaching widgets to parent widgets. 
We saw how geometry management handled the sizing and positioning 
of widgets automatically for us. And we’ve even seen the results of not 
attaching a widget. 

For your convenience we are listing the whole (long and complex) 
open method up to this point. Notice that we have changed the text wid¬ 
get code to drop the explicit sizing, since this would now be automatic. 
These changes appear in boldface: 

open 

' ' open a Counter'' 

| shell main form text rowColumn buttonl button2 button3 | 

shell := CwTopLevelShel1 

createApplicationShel1: 'Counter Example' 
argBlock: nil. 
main := shell 

createMainWindow: 'main' 
argBlock: nil. 
main manageChi1d. 

form := main 

createForm: 'form' 
argBlock: nil. 
form manageChi1d. 

rowColumn := form 

createRowColumn: 'buttons' 
argBlock: [ :w | w 

numColumns: 1; 
orientation: XmVERTICAL; 
packing: XmPACKCOLUMN]. 
rowColumn manageChild. 

rowColumn setValuesBlock: [:w | w 

topAttachment: XmATTACHFORM; 
topOffset: 2; 

bottomAttachment: XmATTACHFORM; 
bottomOffset: 2; 
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1eftAttachment: XmATTACHFORM; 
leftOffset: 2]. 

rowColumn: manageChild 
buttonl := rowColumn 

c reate 1 Pus h Button : 'Add' 
a r g B1o c k: nil. 
buttonl manageChild. 

button2 : = rowColumn 

createPushButton: 'Subtract' 
argBlcck: nil. 
button2 manageChild. 

button3 : = rowColumn 

createPushButton: 'Reset' 
argB1ock: nil. 
button3 manageChild. 

text := form 

create_abel: ' text' 
argBlock:[:w | w borderWidth: 1]. 
text 1abelString: 'O', 
text manageChi1d. 

text setValuesB1ock: [:w | w 

bottornAttachment: XmATTACHFORM; 
bottornOf f set: 4; 
topAttachment: XmATTACHFORM; 
topOffset: 2; 

rightAttachment: XmATTACHFORM; 
rightOffset: 4; 

1eftAttachment: XmATTACHWIDGET; 
leftWidget: rowColumn; 
leftOffset: 5] 
shell realizeWidget. 

You may feel a little uncertain about geometry management. That’s 
okay, as we will cover this subject in greater depth in Chapter 10. For 
now, just think of it as a way to tether widgets together. 



92 


IBM SMALLTALK 


Writing the Methods 

Each of the buttons we’ve defined needs a method to call when it is 
clicked. The methods will be quite similar to one another. We simply 
want to retrieve the present contents of the text field, add or subtract 1, 
and then replace the old value of the text field with the newly calculated 
one. The Reset button simply ignores the present value of the text field 
and forces a zero into it. 

Hie First Method: Increment 

Let’s name the method that gets called when the Add button is clicked 
increment:clientData:callData: . As you can see from this name, we have 
several arguments to the method. The arguments are part of the Com¬ 
mon Widgets callback protocol. What is a callback? In its simplest sense, 
it is the message sent to a widget when a specified action occurs. 

The first argument of this method is always the receiver widget for 
the callback. The clientData: argument can represent any object you 
want to pass to the method. For our purpose, we will assume it is the 
label widget. Finally, callData: is specific to each type of action per¬ 
formed. In our case it will always be nil It is common practice to name 
this parameter “ignored.” 

We have enough information to write our method. Make sure you are 
still browsing CounterWindow. From the pop-up menu of operations in 
the Instance Methods list, choose Template. A new method template 
appears. Replace the template with the following code for the first method: 

increment: aWidget clientData: textWidget callData: ignored 
''Add 1 to the value of the counter'' 
value := value + 1. 

textWidget labelstring: value printstring. 

As you can see, by using the clientData: argument to pass us the label 
widget, we don’t have to find another way to access the object. The only 
other thing we haven’t seen before is the idea of telling an object to 
represent itself as something other than what it is. It would not be legal 
to try to use a number as a label, so we have to trick the program into 
doing so. We do that by sending the printstring message to the value 
instance variable’s contents, which is a number. Viola! A string! 
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Connecting the Method and the Button 

With the increment:clientData:callData method defined, we need a way 
to let the Add button know that when the user clicks on it, it should send 
the increment;clientData:CallData: message to the window. As we dis¬ 
cussed earlier we will need a callback assigned to the button widget. 
Callbacks are assigned in the open method. We will modify the open 
method by adding the following code: 

button 1 

addCal1 back: XmNactivateCallback 
receiver: CounterWindow 
selector: #inc rement:c1ient Da ta:ca 11 Da t a : 
clientData: text. 

Again, add this method to “shell realizewidget.” 

The callback we are interested in is XmNactivateCallback, which is a 
constant representing a Motif C call. This code will send the message 
increment: clientData: callData: to CounterWindow when it is activated. 
The last line sets the clientData argument of the above message to the 
label widget we call text. 

This callback message protocol is the fundamental mechanism by 
which actions such as mouse-clicks are handled in IBM Smalltalk. We 
devote Chapter 7 to a detailed explanation of the process. For now, just 
understand that the purpose of this message is to enable your 
CounterWindow to do something interesting in response to the user’s 
mouse-clicks. 

Making sure you are still browsing CounterWindow, add the above 
code to the open method between “leftOffset: 5]” and “shell realizeWidget” 
and save the changes. 

Start the application, click on the Add button a few times, and ob¬ 
serve the value of the contents of the field change in response. 

The Rest ofl : the Methods 

Simply follow the same procedure we just demonstrated to add the meth¬ 
ods decrement:dientData:callData: and reset:clientData:callData: to the 
application. Here is the code for decrement : 
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decrement: aWidget clientData: textWidget cal 1 Data: data 
''Subtract 1 from the value of the counter'' 
value := value - 1. 

textWidget labelstring: value printstring. 

Here is the code for the resetCounter method: 

reset: aWidget clientData: textWidget callData: data 
''reset the value of the counter’’ 
value :=0. 

textWidget labelstring: value printstring 

Finally, here is the open method in its final, working form, with all of 
the buttons hooked up to their appropriate methods: 

' ' open a Counter'' 

| shell main form text rowColumn buttonl button2 button3 | 

shell := CwTopLevelShel 1 

createApplicationShel1: 'Counter Example' 
argBlock: nf1. 
main : = shell 

createMainWindow: 'main' 
argBlock: nil. 
main manageChild. 

form := main 

createForm: 'form' 
argB1ock: nil. 
form manageChild. 

rowColumn := form 

createRowColumn: 'buttons' 
argBlock: [ :w | w 

numColumns: 1; 
orientation: XmVERTICAL; 
packing: XmPACKCOLUMN]. 
rowColumn manageChild. 

rowColumn setValuesBlock: [:w | w 
topAttachment: XmATTACHFORM; 
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topOffset: 2; 

bottomAttachment: XmATTACHFORM; 
bottomOffset: 2; 

1 eft Attachment: XmATTACHFORM; 
leftOffset: 2]. 

rowColumn mariageChild 

buttonl := rowColumn 

createPushButton: 'Add' 
a r g B1o c k: nil. 

buttonl manageChild. 

button2 := rowColumn 

createPushButton: 'Subtract' 
a r g B1o c k: nil. 

button2 manageChild. 

button3 := ro.A/Column 

createPushButton: 'Reset' 
argBlock: nil. 
button3 manageChild. 

text := form 

createtabel: 'text' 
argB1ock:[:w | w borderWidth: 1]. 
text 1 a be 1 String: 'O' . 

text manageChi1d . 

text setVa1uesB1ock: [:w | w 

bottomAttachment: XmATTACHFORM; 
bottomOffset: 4; 
topAttachment: XmATTACHFORM; 
topOffset: 2; 

rightAttachment: XmATTACHFORM; 
rightOffset: 4; 

1eftAttachment: XmATTACHWIDGET; 
leftWidget: rowColumn; 
leftOffset: 5]. 

buttonl 

addCal1 back: XmNactivateCallback 
receiver: self 
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selector: #i increment: clientDataicallData: 
clientData: text. 


button2 

addCallback: XmNactivateCallback 
receiver: self 

selector: ^decrement:clientData:callData: 
clientData: text. 


button3 

addCallback: XmNactivateCallback 
receiver: self 

selector: #reset:clientData:call Data: 
clientData: text. 


shell realizeWidget. 

We need to make a few points about the code in general. The open 
method is unusually long. In practice, you would break it up into smaller 
methods that would be called from the open method. We chose to leave 
the method intact in order to show the creation of widgets all at once. 

While prototyping it is not unusual, nor incorrect for that matter, to 
use short, general names for variables (for instance, i, j, buttonl, but- 
ton2 ) as placeholder names. To do so is a good idea until the true role of 
the variable becomes clear and thus a more appropriate name is de¬ 
rived. It is good programming style, and will increase the readability of 
your code, if you later change these ambiguous names to something more 
meaningful. 

Finally, we should point out two coding styles that we have adopted as 
a result of our experience with code modification. We leave vertical bars, 
even when no temporary variables have been defined (generally, 
Smalltalkers remove vertical bars unless needed). We’ve found that while 
variables may not be currently defined, they may be in the future, when 
it is easier to define them using this style. We also put periods at the 
ends of the last statements in our methods, again bucking the trend of 
most Smalltalkers. However, we’ve found that if you need to add code to 
the end of a method, it is quite easy to forget this period and get a com¬ 
pile error. Adding it does not hurt the code or its readability but does 
prevent this common error. 
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Saving the Counter Class 

Hopefully, you found the process of creating, testing, modifying, and de¬ 
bugging the Counter class enlightening. However, unless you intend to 
build something more interesting from it, you will probably want to re¬ 
move the class from your image before you save the image again. If you 
leave IBM Smalltalk and don’t save the Environment, your work will not 
be preserved. The easy way to remove your experimental work from the 
image is just to quit and allow IBM Smalltalk to forget your changes. 

If you wish to save your work somewhere for later review but don’t 
want it cluttering up your IBM Smalltalk image, file out the application. 
Simply activate an applications browser (one is probably already open 
and listed on the Windows menu), select the application you want to 
save, and choose File Out and then One Name... from the pop-up menu. 
Later, you can file in the application from the same pop-up menu if you 
want to explore it further. 

There is a lot that could still be done with this project. You may want 
to experiment with changing the font and style of the value shown in the 
field or add color, both of which are relatively easy changes. In the Chapter 
5 folder accompanying this tutorial, you’ll find the Counter application 
as we’ve defined it in this chapter. 




Smalltalk has been a graphical user interface (GUI) from the first ver¬ 
sion of the product, created by the Xerox Palo Alto Research Center 
(PARC) in the early 1970s. In fact, all modern GUIs on desktop comput¬ 
ers have descended from the work done on Smalltalk and its associated 
hardware. 

Early releases of Smalltalk that predated the emergence of modern 
GUI-based operating systems contained their own classes to implement 
the GUI and in fact took over control of the machine, overriding its na¬ 
tive operating system in many ways, to provide Smalltalk developers a 
graphical environment in which to build and deploy applications. As GUI- 
based systems such as Microsoft Windows, the Apple Macintosh, and 
IBM’s OS/2 emerged, the necessity for Smalltalk to provide proprietary 
support for the graphical interface went away. 

Because of IBM Smalltalk’s unique approach to providing a cross-plat¬ 
form language that supports the native platform’s look and feel, the ar¬ 
chitecture in IBM Smalltalk has some unusual and important character¬ 
istics. This chapter focuses on the interface aspect of creating windowed 
GUI applications using IBM Standard Smalltalk. 

From the user’s perspective, the windows—rectangular regions of the 
screen that the user can move, resize, zoom, collapse, open, close, and 
otherwise manipulate—are the primary visible elements of any applica¬ 
tion that runs under Microsoft Windows and IBM OS/2. Windows come 
in a variety of sizes and styles, though all are rectangular. 

The programmer deals with windows and the components contained 
in windows primarily as a way of accomplishing two things: displaying 
information to the user and responding to or managing events triggered 
by the user’s interactions with the windows. 

IBM Smalltalk achieves its cross-platform capabilities due in large part 
to the fact that IBM adopted an industry standard GUI design, namely the 
OSF/Motif standard that is extensively used by UNIX system manufactur- 
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ers. (As we will see in Chapters 10 and 11, IBM also used the underlying 
X-Windows graphical model for graphical compatibility.) 

Many user interface elements are, of course, active. When the user 
clicks on them or types into them, things happen to the widgets and their 
contents or appearance. The management of events, which are really 
communications between widgets, will be discussed in the second major 
portion of this chapter. 

Widgets: An Overview 

The term widgets broadly refers to all of the component parts that can 
be combined in various ways to create user interfaces. The term is in 
wide use in the software industry and is not unique to IBM Smalltalk. Other 
languages and other dialects of Smalltalk include objects that could legiti¬ 
mately be called widgets, but the term is generally not used in those tools. 

At its simplest level, a user interface consists of one or more top-level 
shell widgets (called windows in other languages), each in turn contain¬ 
ing zero or more widgets such as buttons, scroll bars, and text fields. A 
top-level shell can in fact contain other shells that in turn contain shells 
or other component widgets, and so forth, to an arbitrary degree of com¬ 
plexity and depth. 



if you have experience with other Smalltalk dialects, you'll be comfortable with IBM 
Smalltalk if you think of widgets as the equivalent of subpanes in those dialects. For 
example, where you might refer to a text pane in a window in another version of 
Smalltalk, in 1BIVS Smalltalk you refer to the same object as a text "widget" 


A single unified collection of widgets makes up a containment hierar¬ 
chy (as in “top-level shell X contains composite widget Y that in turn 
contains primitive widgets Z and Q”), which is also sometimes referred 
to as a widget tree. 
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Types of Widgets 

Widgets can be divided into three basic types: 

m Primitive widgets, which make up the simplest level and include 
buttons, combo boxes, lists, text labels, and the like 

m Composite widgets, which usually but not always have “children” 
(that is ; widgets they contain) 

m Shell widgets, whose only role is to provide a “home” for compos¬ 
ite and primitive widgets 

All widgets in IBM Smalltalk are part of the Common Widgets subsystem, or 
application. Their names start with “Cw”; this convention makes it easy to 
know when you are dealing with a common widget instance or class. 

Widget Basics 

Every window displayed on the screen of an IBM Smalltalk application 
you create has one and only one instance of CwTopLevelShell (or 
CwDialogShell for dialogs). The purpose of this object is to contain and 
manage the window frame, title bar, and content area. The content area, 
in turn, always holds an instance of CwMainWindow. This main window 
object manages the menu bar for the window and contains a CwForm, 
which is a composite widget into which all other widgets included in the 
window are placed. 

When you are creating a user interface in IBM Smalltalk, you will 
generally work from the top down (or from the outside in, depending on 
your view of the world of geometry). That is, you will create an instance 
of CwTopLevelShell first and then add other widgets to the shell in 
“containership” sequence (that is, widgets that contain other widgets 
are created before the widgets they are designed to hold). 

IBM Smalltalk defines a number of “convenience methods” to make it 
easy to create widgets. These convenience methods always require two 
arguments. The first is a string that names the widget for later reference 
in the program (note that this is not the same as providing a user-read¬ 
able name or label). The second argument is either nil or an argument 
block that provides some parameters or other instructions associated 
with the widget being created. Convenience methods are always sent to 
the object that is the parent of the widget being created. We’ll describe 
some of the more important convenience methods in IBM Smalltalk as 
we discuss individual widgets in this chapter and in Chapters 10 and 12. 
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Once you’ve created a widget, you’re not done. You must still take two 
additional steps before the widget will be displayed and usable: setting 
up its geometry management and causing it to be displayed. 

Setting lip a Widget's Management 

The size and position of a widget must be managed by the widget’s par¬ 
ent. This process is sometimes called geometry management. The child 
widget must be made manageable. 

To notify the widget that it should be managed by its parent, you send 
the widget a manageChild message. (We’ll see shortly what it means to 
have an unmanaged widget, but we can assure you that it is not nearly 
as serious a problem as having an unmanaged teenager or, for that mat¬ 
ter, an unmanaged hairdo.) 

The composite widgets CwForm and CwRowColumn are referred to 
as layout widgets. They allow you to specify with great precision how 
child widgets should be arranged relative to one another and to the com¬ 
posite itself. A series of constants defined in the CwConstants pool dic¬ 
tionary assist in this process. For example, to tell a widget to connect its 
left side to the left side of the CwForm widget containing it, you could 
use the constant XmATTACHFORM . These constants are used in con¬ 
junction with messages with names like leftAttachment: and 
bottomAttachment: , giving you extensive control over the way a widget 
is displayed and resized. 

All of this will become more clear as we work with widgets in subse¬ 
quent chapters of the book. 

Causing a Widget ti lie Displayed 

Widgets remain invisible until they are “realized.” You cause an entire 
widget tree to be realized (displayed) at one time by sending the shell 
widget (the topmost widget in the hierarchy) the realizeWidget message. 
This message causes all of the widgets, including those contained in com¬ 
posite widget objects, to be realized. 
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Mapping a Widget 

We said you have to do two things to a widget to cause it to be displayed 
and usable, but there’s actually a third action that needs to be taken. 
You seldom have to think about this one, though, because IBM Smalltalk’s 
default behavior is almost always what you want. 

A widget must be “mapped” before it is realized, or it won’t display 
even when the top-level shell object receives the realizeWidget message 
discussed in the preceding section. 

By default, all widgets are mapped when they are managed. You may 
occasionally need to unmap a widget so that it won’t be visible, but for 
the most part you can safely ignore this concept. A widget that is un¬ 
mapped takes up space in the window, but the user doesn’t see it. 

Widget Resources 

All widgets have a set of associated resources that describe how the 
widget will look and, to some extent, behave. In IBM Smalltalk, widgets 
have resource methods that provide access to their resources. (You can 
think of resources as analogous to properties; they are characteristics of 
a widget that tell you all of the aspects of a widget’s appearance and 
behavior that you can control.) 

Resource methods are reminiscent of accessor methods for dealing 
with objects’ instance variables. But resources are not identical to in¬ 
stance variables. The most important (though not the only) difference 
between resources and instance variables is that resources are dynamic 
and “hot” (that is, when you change the value of a resource, the change 
is immediately reflected in the widget’s appearance), while changes in 
instance variables do not affect appearance until a specific event causes 
an update. 

All Common Widgets have a core set of common resources, the most 
important of which are reflected in Table 6-1. 
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Table 6-1. Common Widget Core Resources 


RESOURCE PURPOSE/NOTES 


backgroumdColor; 

borderWsdtti; 

foregroundColor; 

height; 

resizable 

userOata 

width; 

x: 


y: 


Defines background color. 

Sets width of border surrounding widget. 

Defines foreground color. 

The height of widget's window, in pixels 

A boolean value indicating whetherthe widget can be resized by 
the user 

A programmer-defined resource that makes it possible for you to 
define new attributes for a widget 
The width of widget's window, in pixels 

The x coordinate of widget's upper-left corner in relation to parent 
(excluding border) 

The y coordinate of widget's upper-left corner in relation to parent 
(excluding border) 


Many of a widget’s resources can be defined using built-in constant 
values. These constants are stored in an IBM Smalltalk pool dictionary 
called CwConstants. As a result, any application you build should in¬ 
clude a reference to that pool dictionary in the class definition of any 
class that uses a widget constant (remember that pool dictionaries are 
not inherited). 

Widget Functions 

In addition to resources, widgets have functions. All methods that aren’t 
used to get or set a resource are function methods. 

Some widget function methods change a resource value as a side effect. 
For example, if a widget defines a function method that changes the label it 
displays, this method will also alter the widget’s value resource. 

A Brief Example 

Let’s take a quick look at the basic use of widgets as we have described 
the process. We’ll build a small window in stages so that you can get a 
feel for what happens at each level of complexity. 

Type the following code into a Workspace or the System Transcript, 
select it and Execute it. The result isn’t very gratifying (but at least it 
doesn’t blow up). 
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| shell main | 

shell := CwT o aLevelShel1 

createApplicationShell: 'My First Window' 
argBlock: nil. 

main := shell 

createMainWindow: 'main' 
argBlock: nil. 
main manageChild. 
shell realizeWidget. 

You end up with a tiny “window” consisting of only a title bar, a system 
(or control) menu, and minimize and maximize controls. It has no con¬ 
tent area, and its label is not entirely readable. 

Still, this small code segment teaches us a couple of things. You can 
see that we have two convenience methods called: createApplicationShell: 
and createMain Window: . Each of them provides a nil second argument. 
You can also see that when the main window is created, it sends itself a 
manageChild message. Finally, notice the realizeWidget message sent to 
the top-level shell object in the last line. The basics are clearly all here. 

What is needed is a content region for the window. Let’s add that 
next. Here’s the same code as we just saw, with added material in bold 
so you can easily see what to change. (Don’t forget to add the local vari¬ 
able form to the first line of the code.) 

| shell main form | 
shell := CwTopLevelShel1 

createApplicationShell: 'My First Window' 
argB1ock: nil. 

main := shell 

createMainWindow: 'main' 
argBlock: nil. 
main manageChild. 

form := main 

createFcrm: 'form' 
argBlock: nil. 
form manageChild. 
shell realizeWidget. 
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Select and execute this code, and you’ll be much happier with the 
result. You now have a window that you can see. 



We generally try to isolate you from the "guts" of the underlying operating system in 
which you program using IBM Smalltalk, hut we just couldn't resist this little aside. 
Creating a do-nothing window like the one we just created with 13 lines of IBM 
Smalltalk code requires dozens of lines of code spread over four C source code files 
and a make file to compile the others. Not bad, eh? 


Let’s add one more element to our window before moving on. If you 
experimented at all with the window we created in the last step, you’ve 
found you can’t do much with it beyond move, resize, minimize, maxi¬ 
mize, and close it. The content area isn’t responsive to your mouse-clicks. 
Let’s add an editing area to that part of the window. 

Here’s a modified version of the above code, again with changes (in¬ 
cluding yet another local variable) in bold: 

| shell main form editArea | 
shell := CwTopLevelShel1 

createApplicationShel1: 'My First Window' 
argBlock: ni1. 

main := shell 

createMainWindow: 'main' 
argB1ock: nil. 
main manageChild. 

form := main 

createForm: 'form' 
argBlock: ni 1 . 
form manageChild. 

editArea := form 

createScrol1edText: 'text area' 
argBlock: [ :w | 

w width: 300; height: 300; borderWidth: 1]. 
editArea manageChild. 
shell realizeWidget. 
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Notice that the editArea object we create with the createscrolledText: 
message doesn’t have a nil argument block for its second argument. 
Instead, there’s a block of code that sets up the width, height, and bor¬ 
der thickness for the new widget. 

Select the code and execute it. Now you should be able to type text 
into the content region of the window. 

Some Final Tlioiigbts about Widgets 

We’ve barely scratched the surface of widgets. These objects are so cen¬ 
tral to IBM Smalltalk’s way of looking at the world of applications that 
we’ll encounter them time and again throughout this book. But a few 
miscellaneous ideas are worth at least broaching now. 

You do not normally have to worry about destroying a widget you’ve 
created. When the top-level shell (window) is closed, IBM Smalltalk will 
handle destroying all of its contained objects and releasing the memory 
associated with them. 

It is considered good programming practice in IBM Smalltalk to de¬ 
fine resources in the block argument (the second argument) to the cre¬ 
ation convenience method wherever possible. On most platforms, doing 
so results in considerable performance enhancement. 

You seldom need to concern yourself with sizing container objects in 
IBM Smalltalk., Other dialects require you to define the size of a window 
or top-level pane explicitly in your code. You can spend a lot of time 
tweaking position and size. IBM Standard Smalltalk removes most of 
that concern. When you relate widgets to one another in a containment 
hierarchy and tell each object to allow itself to be managed, IBM Smalltalk 
takes over management, automatically sizing container widgets appro¬ 
priately. You’ll come to appreciate this convenience. 

lliderstaiding Events 

IBM Smalltalk provides two different mechanisms for dealing with two 
different classes of events that take place in a modern event-driven ap¬ 
plication. Much of the code in the methods responsible for opening and 
managing shell widgets and their contents is devoted to responding to 
these events. 

When users interact with your application, they undertake specific 
tasks such as typing text into a text widget, clicking on button widgets, 
resizing windows, or opening menus. You can think of these as high- 
level events. IBM Smalltalk provides a mechanism known as callbacks 
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to allow you to define your application’s response to this type of event. 

At the same time as users see themselves as engaging in high-level 
events, there are low-level events taking place in your application. For 
example, when the user selects an item from a list widget, that is a high- 
level event. Underneath that event are low-level events including mouse 
button presses and releases and mouse pointer motion. Similarly, when 
they type text into a text widget, the low-level events of individual key 
presses and releases on the keyboard are being generated. To deal with 
such events in your IBM Smalltalk application, you need to design event 
handlers. 

Events are really the heart of applications built on modern GUIs. 

Dealing with High-Level Events 

When you create widgets that are potentially interactive, you will almost 
always define a callback method to be triggered by each high-level event 
with which the widget will have to be concerned. Each type of widget is 
capable of responding to a finite set of such high-level events. This pro¬ 
cess of defining callbacks is often referred to as “registering” callbacks. 

You register a callback using the addCallback:receiver:selector:clientData.■ 
method. (Quite a mouthful, eh?) As you can tell by looking at it, this 
method requires four arguments. The first is a constant (defined in the 
Pool Dictionary CwConstants ) that specifies the callback being registered. 
The second is the object that will receive the callback message; gener¬ 
ally, but not always, this is the special variable self, which refers to the 
instance of the class in which the selector is defined, usually the window 
creation class. The third argument is itself a three-argument callback 
message selector defining the method to be invoked when the callback 
occurs. The fourth argument is either nil or contains optional data to be 
passed to the callback method defined in the third parameter when it is 
executed. 

When a callback method is invoked, it receives three arguments (which 
is why the selector defined as part of its registration must be a three- 
argument callback message selector). These three pieces of data are the 
widget that caused the callback, the client data specified when the call¬ 
back was registered (if any), and information specific to each type of call¬ 
back. This last piece of information is referred to generically as call data. 

This sounds a lot more complex than it actually is. Let’s take a look at 
a short example to see the process in action. The following code creates 
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a button as the child of a shell widget. It defines a callback for the 
XmNactivateCallback event. This callback is triggered whenever the user 
activates a button by pressing the mouse button when the pointer is over 
the button widget. 

| shell button | 
shell := CwTopLevelShel 1 

createApplicationShell: 'shell' 
argBlock: nil. 
button := sheil 

createPushButton: 'OK' 
argBlock: nil. 

button 

addCal1 Back: XmNactivateCallback 
receiver: self 

selector: #pressed:clientData:callData: 
clientData: 'Ouch! You clicked me!', 
button manageChild. 
shell rea1ize^idget. 

Notice that the argument to the selector: portion of the message that 
registers the callback is a symbol (preceded by the special character 
Omitting this hash mark (or pound sign, if you prefer) is a source of 
common errors in IBM Smalltalk programming. With the symbol, IBM 
Smalltalk treats the entire argument as defining a method named 
pressed:clientDatci:callData:. Without the hash mark, IBM Smalltalk 
would try to interpret the argument as a method call, resulting in seri¬ 
ous bugs! 

Having identified a method to be called when the XmNactivate event 
occurs, you must of course define that method. This method is defined in 
the class of the receiver object you specify as an argument to the call¬ 
back, in this case, self. Here is how it might look: 

pressed: widget clientData: clientData callData: callData 

"The button was pressed, creating an XmNactivate callback event." 

Transcript cr; show: clientData 


In conjunction with the earlier code that placed the string “Ouch! You clicked 
me!” into the clientData of the callback, this code would result in that string 
being displayed in the System Transcript when the button is pushed. 
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You can, of course, define more than one callback method for a wid¬ 
get. For example, a CwList widget might need a method to respond when 
the user selects a single item, another method for when the user selects 
multiple items, and still another for when the user asks for help when 
the list is active. 

We’ll have lots of opportunities to see high-level callback handlers at 
work in the rest of the book, but the basics remain the same. To define a 
callback for a widget, you merely: 

b Create the widget. 

b Send the widget an addCallBack:receiver:selector:clientData: 
message. 

m Define the method identified in the third argument to the above 
message. 


Dealing with Low-Level Events 

Sometimes you need to deal with events at a lower level than the 
user’s intent. When the user activates a pop-up menu and selects an 
item from it, for example, you may need to intercept the initial mouse- 
click to put updated options into the menu before displaying it. 

Dealing with low-level events is very nearly identical to dealing with 
high-level events except that the method you use is called 
addEventHandler: receiver: selector: clientData:. The first argument dif¬ 
fers from that required by the addCallbackHandler.... message we saw 
in the preceding section, but the remaining arguments are the same. 

The first argument to the addEventHandler:... message is an event 
mask that tells your application which type or types of events it should 
expect to monitor. Table 6-2 identifies the event masks defined in IBM 
Smalltalk. You combine these masks using the vertical bar operator (“I”), 
which is the symbol for a logical OR operation. 
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Table 6-2. Common Widget Event Masks 


EVENT MASK 

U 

EVENT TYPE 



KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

PointerMotionMask 

Button! Motion Mask 

Button2MotionMask 

Button3MotionMask 

ButtonMotionMask 

ButtonMenuMask 


Keyboard key-down 
Keyboard key-up 
Mouse button down 
Mouse button up 
Mouse movement 

Mouse movement with button 1 held down 
Mouse movement with button 2 held down 
Mouse movement with button 3 held down 
Mouse movement with any button held down 
Pop-up menu request 


For example, you might define a CwDrawingArea widget in which 
you expect the user to draw by dragging the mouse pointer around. This 
widget needs to be able to respond to button-down, button motion, and 
button release events, so you might define its event handler in a frag¬ 
ment that looks like this: 


drawing "assume this is the name of the widget" 

addEventHandler: ButtonPressMask | ButtonMotionMask | 
ButtonReleaseMask 
receiver: self 

selector: #eventHandler:clientData:event: 
c1ie n t D a t a: nil. 


Hens ii I6H Smalltalk 

In contrast to other dialects of Smalltalk, IBM Smalltalk maintains the 
consistency of its architecture when dealing with menus. In fact, menus 
are instances of CwRowColumn, though you seldom have to deal with 
this fact at all. 

IBM Smalltalk includes three convenience methods for creating menus: 


m createSimpleMenuBar-.argBlock : 
m createSim plePulldownMenmargBlock: 
m createSimplePopupMenwargBlock: 
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The first argument to each of these methods is a string containing the 
name of the menu to create. The second argument is a block that can 
vary from quite simple to complex depending on whether you use hier¬ 
archical (cascading) menus, how many menu items a given menu con¬ 
tains, and the like. As implied by the names of these methods, there is 
also a complex menu structure. We will see this in a later chapter. 

Here is a code fragment that creates a File menu with two options: 
Open and Close. The first letter of each option is defined as a mnemonic, 
and a divider line separates the two items. (Note that this is not a com¬ 
plete method, so don’t try typing it and saving it.) 

menuBar :=mainWindow "mainWindow is the name of the top-level shell." 
createSimpleMenuBar: 'bar' 
argBlock: [:x | 
x 

buttons: #('File'); 
buttonMnenomics: #($F)]. 

fi1eMenu := menuBar 

createSimplePulldownMenu: 'file' 
argB1ock: [:x | 
x 

buttons: #('0pen' 'separator' 'Close'); 
buttonType: (Array 
with: XmPUSHBUTTON 
with: XmSEPARATOR 
with: XmPUSHBUTTON); 
buttonMnemonics: (Array 
with: $ 0 

with: 0 asCharacter "no mnemonic for the 
sepa rator" 
with: $C); 
postFromButton: 0]. 

As with any other interactive widget, you would also have to define an 
addCallback:... method to this menu widget to enable it to respond to 
the user selecting one of its options. 

The menu bar itself has a simple argBlock:. It simply defines a label, 
“File,” and a mnemonic, the single letter “F.” (The dollar sign, as you’ll 
recall from Chapter 2, indicates a character value.) 




CHAPTER 6: WIDGETS AND EVENTS 


113 


The menu items attached to the File menu generate a substantially 
more complex argBlock:, but its organization is fairly straightforward. It 
has four primary elements. The buttons: message includes an array as 
an argument ( the “#” preceding a parenthesized list of objects generates 
an array). The three members of this array are all strings. The first and 
last define menu items; the second defines a separator line. 

Each of the next two arguments must be an array of the same size. 
There is, as you can probably infer, a mapping among the elements of 
these arrays. The first element in the first message, buttons:, is called 
“Open.” It corresponds to the first item in the next array and is therefore 
a push-button (defined by the constant XmPUSHBUTTON) whose mne¬ 
monic is the character “0” (as defined in the third array). 

Finally, the last entry in the above code fragment, postFromButton:, 
tells the fileMenu to attach itself to the zero position on the menu bar. 
Since the menu bar’s menu positions are numbered from zero, this means 
the File menu will occupy the first position on the menu bar. 

Again, as with the other widgets we’ve looked at in this chapter, we’ll 
see many more menus as we build the sample applications and projects 
in this book. 




CHAPTER 


The Third Project: 



In this chapter we will build our third project, a calendar application. 
This application will form the basis for all of the remaining five projects 
in the book: an appointment book capability in Chapter 9, a business 
graph in Chapter 11 that we extend in interesting ways in Chapter 13, 
and a file storage mechanism and a clock with alarms in Chapter 15. 
The result will be a simple personal information manager (SimplePIM) 

We will again take a slightly different approach from earlier projects to 
the development of this application. We will discuss and provide examples 
of the process of exploratory programming. This is not so much a program¬ 
ming technique as a method for finding out what is in the complex IBM 
Smalltalk environment and what you can do with what is there. We spend a 
great deal of our programming time doing just such exploration. 

We will begin with a description of what we want the program to 
accomplish. Next, we’ll get into serious exploration and look into the Smalltalk 
class Date to discover behaviors that we might implement in our appli¬ 
cation. Then we’ll discuss the creation of the window to display our cal¬ 
endar. We will then create the Calendar object itself, followed by the 
class that will hold the application. In constructing the application, we’ll 
focus on its event handling. After testing the application to ensure it does 
what we want, we’ll make a couple of refinements to demonstrate again 
the advantages of OOP and Smalltalk for extending existing software. 
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The Application Design 

We want to keep calendar functionality simple so we can concentrate on 
programming issues involved in its creation. We will model it after a 
standard wall calendar (without the pretty picture, of course). We will 
be able to mark important dates and holidays and flip between months 
easily. Unlike its real-world counterpart, our calendar won’t “expire” on 
December 31 this year; we’ll design it to support all the years from 1900 
to 2100. 

Finally, we’ll build in the ability to search for a specific date and auto¬ 
matically flip to its month display. 

Exploring Design Issues 

Two components we’ll certainly need in this application are date objects 
and a window object of some sort to handle events related to the user’s 
interaction with our calendar. We’ll adopt an exploratory approach to 
these issues. 


Staying in Sync 


Before we proceed, and to be sure 
TrailBlazer options are set as: 
n Default Private Methods Filter 
a Enable Method Categories 
m Default Method Inheritance 
is Show Classes Hierarchically 
■ Show Public/Private Buttons 


we are in sync, make sure your 


off 

off 

No Inheritance 
on 

off for both 


You will need to open a new browser for the changes to take effect. In 
subsequent chapters we will assume these settings. 


Setting lip the Application 

We need a new application in which to carry out the tasks in this chap¬ 
ter, so let’s create one, using the applications browser. As part of the 
process, we will need to use the right mouse button to open a context- 
sensitive pop-up menu. To make things easy, we’ll use the term “pop-up 
menu” to refer to this menu. We will also refer to the lists by their combo 
box selections, such as “Loaded Applications.” The both m area of the 
window has its own combo box for choosing the prop „ ' - P* p- 
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erties include source, comment, notice, and prerequisites; more will be 
said on each as we use them. The property to view can also be set by 
choosing Show Property from the pop-up menu. 

Open an applications browser on Loaded Applications. From the pop¬ 
up menu, select Create, then choose Application... from the submenu. 
Name the new application SimplePIM. The application will be created 
and selected. 

We need to define prerequisite applications to be used by our new 
application. Prerequisites contain classes that must be loaded for your 
application to run. Look at the lower part of the window and you will see 
two lists. The rightmost list contains the current prerequisites, while the 
available applications are in the list on the left. The application Kernel is 
automatically added for you. Add the application CommonWidgets as a 
prerequisite by selecting it in the left list and clicking on the »> button. 

Next we will create the classes for our application. We’ll begin with de¬ 
fault definitions, which we will fill in later. We need two classes, Calendar 
and CalendarWindow. For each class, click on the Object class in the Classes 
list, select Add, then, from the submenu, select Subclass of Selected Class. 
Finally, make the class a type of subclass. Later you will load a more com¬ 
plete copy of the SimplePIM project with all the class definitions, descrip¬ 
tions, and variables defined from the disk accompanying this book. 

When you have set up the application correctly, your applications 
browser window should look like Figure 7-1. 



PI atf o rm Fra m ev/o rk... 
Platform Interface... 
PlatformWidgets... 

Swapper... 

TrailBlazer... 


Calendar 

CalendarWindow 

SubApplication 

Application 

SimplePIM 


nil subclass: ^Object 

instanceVariableNames: " 
classVariableNames: 'Dependents ' 

poolDictionaries: 'SystemPrimitiveErrors SystemExceptions 1 




The applications browser in prerequisites property view after setup is complete 
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From the Transcript Smalltalk tools menu, select Manage Application 
then the SimplePIM application. Now, from the pop-up, select Become 
Default. This choice establishes SimplePIM as the default application. 
Close the application manager browser. 

While following along with the first part of this discussion, you may 
find it useful to open a second browser on the loaded classes. You can do 
this by selecting Open Classes from the Image menu of your current 
browser. We will refer to the two browsers as the applications browser 
and classes browser. 

Looking at the Dote Class 

We will work with dates in our calendar application, so let’s look for 
methods in the class Date that we may find useful. You may want to 
open a new Workspace to use for this exploration; that will enable you to 
copy and paste working code if we build anything useful during this 
exploratory phase. (However, producing useful code will be a side effect 
of the exploration, not its goal. Exploration may produce nothing very 
usable, but you learn things in the process that aid in coding when the 
time comes to create useful things later.) 

In the classes browser, find the class Date by selecting Find... from 
the pop-up menu. Enter Date as the class to find. Let’s look first at the 
class methods, so select Class Methods from the Instance Methods combo 
box. 

There is no new or new: method, so how is a new instance of Date 
created? Notice the method called today. Let’s try sending this message 
to the class Date: 

Date today 

The method responds with the current date formatted as mm/dd/yv or 
mm-dd-yy, depending on your Windows or OS/2 system settings. The 
method newDay:month:year: also creates a date. Before we do any fur¬ 
ther exploration, let’s create some global variables to work with. ( We 
should point out that global variables are not normally used in Applica¬ 
tions, but they can be quite useful during exploration.) Enter and select 
each line below, then choose Execute from the pop-up menu. 


Smalltalk at: #Scott put: nil. 
Smalltalk at: #Tigger put: nil. 
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Now we are ready for some more code. In the Workspace, try some¬ 
thing like: 

Scott := Date newDay: 15 month: #September year: 1994. 

Choose Display to create a new instance of the class Date. Sending 
Scott a message corresponding to an instance method of class Date will 
reveal something. Try typing this line into the Workspace and displaying it: 

Scott monthName 

Smalltalk answers #September, exactly as we’d expect. Now type this 
line into the Workspace and evaluate it: 

Scott dayOfMonth 

Not surprisingly, the answer returned is 15. 

There are obviously many things we can do with Date objects. Here’s 
another. Sometimes, we need to get the number of the month in which a 
date occurs. It’s trivial for us to see this when we see the date as a date 
value like “04/05/94” but less obvious if we use a string or a variable to 
name the date. Type this line into a Workspace and Display. 

Scott monthlndex 

You should now see the number 9 in the Workspace, indicating that 
the date you have supplied is in the ninth month. There are other meth¬ 
ods for date creation as well. The newDay: year: method requires you to 
enter the number of the day of the year for the date you want to create: 

Scott := Date newDay: 360 year: 1994 

Still another method accepts a monthlndex instead of a name: 

Scott := Date newDay: 15 monthlndex: 12 year: 1994. 

Returning to the original version of the method, you can also use a 
three-letter month abbreviation: 


Scott := Date newDay: 15 month: #Sep year: 1994. 
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and even a short year such as: 

Scott := Date newDay: 15 month: #Sep year: 94. 

But wait, why don’t we try this: 

Scott : - Date newDay: 15 monthlndex: 12 year: 1994. 

Tigger : = Date newDay: 15 monthlndex: 12 year: 94. 

Scott = Tigger. 

What is going on here? Display each line below for the answer: 

Scott year 
Tigger year 

You see, the short year is actually the year 0094, not 1994. It’s a good 
thing we checked. 

Here’s one you probably wouldn’t expect to work: 

Scott := Date newDay: 15 month: #Septe year: 94. 

Apparently the method will recognize any symbol containing a 
substring of a month name. (Actually, it answers the first month of the 
year matching the substring, so “J” would answer January and “A” would 
answer April.) We can even create a date by entering the number of days 
since January 1, 1901. The following code returns a date of 12/09/94: 

Scott := Date fromDays: 34310 

Finally, we can create an instance of time set to today’s date and time 
with this line: 

Date dateAndTimeNow. 

Now we know that we can create a new instance of class Date by 
sending the newDay:month:year: method to the class and passing the 
components of a date as parameters. If you’re interested, take a few 
moments to explore the newDay month: day: method to see what works. 

Creating single dates may not be very valuable, but at least we know 
how to do it and we’re getting more comfortable with this class. Let’s see 
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if the class defines any methods that may help in creating a calendar for 
a given month. 

Many of the class methods provide useful utilities related to dates. 
For instance The method dayOfWeek: answers the day index from 1 to 7 
representing the days of week Monday through Sunday. Try it: 

Date dayOfWeek: ^Monday 

The method requires the full day-of-the-week name. A partial name, 
such as #Mon, will result in an error. This method has an opposite that 
returns the name of the day, given a day index: 

Date nameOfDay: 2. 

Similar methods exist for the month name and index 

Date indexOfMonth: #September 
Date nameOfMonth: 9 

The first method will accept a month name of any size just as did the 
newDay:month:year: method we looked at earlier. These methods de¬ 
pend on the class method match which is of interest itself. The method 
answers a complete month name when given a partial month name. Try 
these examples: 

Date match: '/Jan. 

Date match: #janua. 

Date match: #j. 

As you can see, the method ignores case as well as size. And if you should 
be so brave as to give it only one letter of the month, it answers the first 
month in the year that starts with that letter. A very nice and well-be¬ 
haved utility! 

There’s also a method that responds with the number of days in a 
given month and year: 

Date daysInMonth: #Dec forYear: 1994 

This method also allows partial month names and has an index version: 


Date daysInMonthlndex: 9for Year: 1994 
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Please note, this is a private method. Returning to the other side, let’s 
explore Date instance methods to see if we can find any methods that 
will help define a calendar. Be sure to select Instance Methods from the 
Class Methods combo box or, as an alternative, select it from the Classes 
Show pop-up menu choice. 

First we will assign today’s date to a global variable that will become 
our test instance: 

Scott := Date today. 

Now we can send messages of interest to the instance. To generate a 
calendar for any month, we need to know the number of days it has and its 
starting day. Checking the list of instance methods, we find two promising 
candidates, daysInMonth and firstDayOfMonth. Let’s try each of them: 

Scott daysInMonth 
Scott firstDayOfMonth 

The first method works fine, but the second returns the date of the first 
day, which isn’t very helpful. Don’t forget daylndex, which, like the class 
method we saw earlier, answers the instance’s weekday as an index from 
1 to 7, representing Monday through Sunday. 

Scott firstDayofMonth daylndex 

This is exactly what we need. We can now create dates, and from the 
created instance we can determine the month name, the year, and the 
starting day and length of each month. With this knowledge we should 
be able to create a monthly calendar. 

Still, single dates are a far cry from a collection of dates to form a 
monthly calendar. Creating an ordered collection of dates may be the 
key. We know Smalltalk is very good at handling collections of objects. 
Perhaps we can create a month by collecting dates in proper rows and 
columns. Rows and columns sound familiar. In Chapter 5, we discussed 
a widget called CwRowColumn that collects its children into rows or 
columns. We’re onto something here. Perhaps we should move our ex¬ 
ploration over to this widget. 
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In this section we will be exploring the Smalltalk programming examples. 
If you have not done so already, load the examples by selecting Install 
from the Transcript Smalltalk Tools menu. In the resulting dialog, select 
Smalltalk Programming Examples, then click OK. The examples will be 
loaded. This process may take a while, so you may want to take a break. 
At the end of the installation, you will be asked if you want to save the 
image and if you want to delete the source file. Answer these questions 
according to your preferences. 

To begin our exploration, we will use the Find command found in the 
Loaded Classes pop-up menu. We will do a wildcard search on all classes 
dealing with rowColumns by entering the following in the dialog: 

*rowcolumn* 

Click the OK button and look at the resulting list. There are several 
choices. CwRowColumn is the widget class, but there is a class that sounds 
interesting called CwRowColumnExample. This looks like a class worth 
some exploration, so choose it. The first thing we see is that it is a sub¬ 
class of a class called WidgetApplication that is itself a subclass of the 
class WidgetWindow. This is very curious indeed. Now how do you sup¬ 
pose we run this example class? Let’s see if the comments for the class 
provide any clues. From the Loaded Classes pop-up menu, choose Show 
Property, then Comment. (This is the pop-up version of making a selec¬ 
tion from the Property View combo box). The comment does explain the 
example and tells us how to run it. The easiest way to test it is to select 
the text in the comment and Execute it. 

That tells us how to open the example window. Very nice! Starting 
from this example, we should be able to explore this form class thor¬ 
oughly (see Figure 7-2). First, try changing the orientation of the form. 
As you may Lave noticed, the example allows us to see the results of 
setting different attributes. We discussed in the last chapter how these 
attributes are assigned when the widget is created, but here we see that 
the assignments can be made on the fly as well. Continue to explore the 
example until you feel you have a good grasp of how this form works. 
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Image Edit Options Workspace Help 
Loaded; Glasses 

WidgetWindow 
^^^WidgetA^p licaticm^ 

XmListExample 


Orientation Packing Radio Children 


Button -1 


Button ^— 8 


Button 


Button - 2 


Button 


Button 


Button — 3 JO Button 


CwRowCoIumnExample 


Button 


Common Widgets Exampi 


Button 


Button 


Button — A 


SYNOPSIS 


Button — 5 


Button 


"Open the example window." 
CwRowCoIumnExample new open, 


The results of opening the CwRowCoIumnExample program 


Let’s take a moment to explore some of the tools that will help us take 
a closer look at this widget as well as other objects. 

With a Little Help froi Our Tools 

Close the current window and reopen it using Inspect instead of Ex¬ 
ecute. This little trick opens the window and an inspector for the win¬ 
dow. The inspector allows us to look at the internals of the widget tree 
and in particular the rowColumn form. Double-click on the word 
“rowColumn,” representing an instance variable, in the left list. A new 
inspector opens exposing the guts of the form itself. Notice all the Xm 
words in this list. These are the instance variables that hold the attributes 
assigned to this widget. Appendix A of the IBM Smalltalk Programmer's 
Reference lists each widget and the attributes available to it. 

To match the inspector contents with the table in the manual, drop 
the prefix XmN from each variable name. For example, scroll the in¬ 
spector down until to you see XmNButtons. This entry corresponds to 
the table entry labeled Buttons. You may be wondering why there are 
more XmN entries displayed in the inspector than are explained in the 
table. Remember, the inspector is displaying all instance variables, in¬ 
cluding those inherited from parent objects. 

Let’s try changing some of the attributes and see the results in our 
example window. First find XmNnumColumns in the inspector. Accord¬ 
ing to the manual, this variable sets the number of columns in the form. 
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BBS 


CwRowColumnExarnpie 


Orientation Packing Radio Children 



Figure 7-3. 


The results of changing the rowCoIumn numColumns attribute 


In the right-hand portion of the inspector window, type 7 and choose 
save from the pop-up menu. Yes, you just changed the value of an in¬ 
stance variable. This ability can sometimes help you to understand an 
object, especially a visible object, such as a widget. 

Let’s see the results. Make sure the packing menu has columns cho¬ 
sen. From the orientation window, choose Horizontal, then Vertical again 
(see Figure 7-3). 

As you can see, we had a dramatic effect on the example, but at the 
same time we have discovered something quite useful. Imagine the but¬ 
ton labels sho wing only numbers. Would that look like a calendar? Let’s 
try it and see. 

For this trick we will need assistance from the form widget’s children. 
First, let’s make sure all children are displayed equally. Change 
XmNadjustLast to false by selecting the instance variable in the inspec¬ 
tor, then replacing true with false and saving it. 

Now for the children. Double-click on the instance variable 
XmNChildren. This action opens an inspector on the collection of but¬ 
tons in the form. We will directly manipulate this collection to change 
the labels of the buttons. Nothing up the sleeve, except a reference to 
self and a rather long do block that copies a segment of each button’s 
label. Set the inspector and the example window so you can see both; 
you won’t want to miss this. Click on self in the Inspector Window, then 
replace the text in the right section of the window with this code: 
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I s | 

self do: [:c | 

s := c labelstring size. 

c labelstring: (c labelstring copyFrom: s - 2 
to: s) ]. 

Catch the results in Figure 7-4. 

Select and execute the new code. Almost like magic the buttons resize 
and display their new labels. What is even more amazing is how we can 
access the object using self, as if we were writing a method. Just another 
way IBM Smalltalk outperforms those third-letter-in-the-alphabet languages. 
(Enough gloating, back to work.) As you can see, this looks almost like a 
two-week calendar. With some modification, we can make it look even more 
like a calendar. We will need to change some code in the example, so to 
move forward, close the example and all the inspector windows. 

We will begin our investigation of the CwRowColumnExample class 
with a quick look at the open method. But wait, where are the methods? 
Let’s find out if they are all private. From the Instance Methods list pop¬ 
up menu select Public/Private, then select Both from the submenu. There 
are the methods. One of the first things we notice is the absence of an 
open method. It must be an inherited method. Select the Widget- 
Application class. There is the open method. Click on it. It looks some¬ 
what familiar, but it isn’t exactly what we were expecting. We’ll need to 
extend our search to the methods used by this method. 



Figure 7-4. 


The Inspector, the code, and the example after the magic has been performed 
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This seems like an excellent opportunity to fill the Trail End list in the 
TrailBlazer with something a little more interesting. From the list’s combo 
box select Messages Sent. The list is now filled with the messages sent 
by the method. Click on the method createWindow to view the code of 
this method. 

Notice that another list titled “Local Implementers” is created and 
that it displays the other classes that implement this method. The scope 
is referred to as local because it is confined to the present class, its su¬ 
perclasses, and its subclasses. Click on the createWindow method for 
the Widget Application. The browser can be further extended to display 
messages sent by this method. From the pop-up menu select Show, then 
Messages Sent from the submenu. This scrolls the lists again to a new 
“Messages Sent” list. Click on the method createWorkRegion, and a new 
“Local Implementers” list is scrolled into view. Scroll this list to see if the 
class CwRowColumnExample is in it. It is; here is its code: 

CreateWorkRegion 

"Private - Create the receiver's workRegion 
widget hierarchy." 

| aRowCol umn aButton dashes | 

"Create the RowColumn." 

self rowColumn: 

(aRowColumn := self mainWindow 
createRowColumn: 'RowColumn' 
argBlcck: nil). 

a RowColumn 

marginHeight: 5; 
marginWidth: 5; 
numCol unins: 3; 
orientation: XmVERTICAL; 
packing: XmPACKCOLUMN; 
radioBehavior: true. 

"Add some buttons to the RowColumn." 

1 to: 14 do: [:i | 
i \\ 4 = 0 
ifTrue: [ 


aButton := aRowColumn 
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createToggleButton: 'button' 
argBlock: nil] 
i f F a 1 s e : [ 

aButton := aRowColumn 

createPushButton: 'button' 
argBlock: nil], 
dashes := String new: i . 
dashes atA11 Put: $-. 
aButton 

labelstring: CafPLButton, ' ', dashes, ' ', i printstring; 
manageChiId]. 

aRowColumn manageChild. 

self workRegion: aRowColumn 

The code is long and a little complicated, but we can see that it cre¬ 
ates the rowColumn we have been playing with. This is where we want 
to make our modifications. The first thing we should do is make sure we 
have a copy of this method. 

Scroll back to the first list, “Loaded Classes,” and select the 
CwRowCoIumnExampie class again and then the method createWork- 
Region. Add the word “Old” to the end of the name of this method and 
save it. We now have a copy of the method called createWorkRegionOld. 
Reselect the createWorkRegion method. 

Now let’s add the modifications we made when we were in the inspec¬ 
tors. Here is the code segment with these changes (changes are in bold): 

a RowColumn 

marginHeight: 5; 
marginWidth: 5; 
numColumns: 7; 
orientation: XmVERTICAL; 
packing: XmPACKCOLUMN; 
radioBehavior: true; 
adjustLast: false. 

Now we will change the loop code that follows the above section so 
that it will display more than two lines. We will also remove the code 
that creates the long button name and use only the loop integer as a 
label. Finally, just to see how it looks, we will replace toggle buttons with 
labels. Here are those changes: 
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"Add some buttons to the RowColumn." 

1 to: 42 do: [:i | 

1 \\ 4 = 0 
IfTrue: [ 

aBir:ton := aRowCol umn 
createLabel: ' button' 
argBlock: nil] 
i f F a 1 s e : [ 

aBucton := aRowColumn 

createPushButton: 'button' 
argBlock: nil]. 

aButton 

label String: i printstring; 
m a n a g e C h i 1 d ]. 

Save the method. To test it, click on CwRowColumnExample again 
and select the comment property, then select the appropriate text and 
Execute it (see Figure 7-5). Notice we changed the label, making it un¬ 
necessary to use dashes, so all code pertaining to dashes was removed. 
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Well, this isn’t bad at all. The labels tend to look better than the big 
gray buttons. It looks fine except for the numbers being out of sequence. 
Perhaps we should change the orientation to horizontal. That puts the 
numbers in sequence, but now there are only six columns. Let’s try chang¬ 
ing numColumns to 6, and let’s change the orientation to horizontal. 
While we are at it, let’s make all buttons labels. We’ll make this modifi¬ 
cation to our code and test it again. Here is the affected code segment 
with changes in bold: 

a RowColumn 

marginHeight: 5; 
marginWidth: 5; 
numColumns:6; 

orientation: XmHORIZONTAL; 
packing: XmPACKCOLUMN; 
radioBehavior: true; 
adjustLast: false. 

"Add some buttons to the RowColumn." 

1 to: 42 do: [:i | 
i \\ 4 = 0 
ifTrue: [ 

aButton := aRowColumn 
createLabel: 'button' 
argBlock: nil] 
i f F a 1 s e : [ 

aButton := aRowColumn 
createLabel: ' button' 
argBlock: nil]. 

aButton 

label String: i printstring; 
manageChiId]. 

aRowColumn manageChild. 

A little cosmetic surgery and we may just have something. What we 
need to do is to limit the display to only 31 days and to fill in the rest with 
spaces. We’ll modify the conditional portion of the loop to accomplish 
this. The code needs to be manipulated quite a bit for this, so we will 
show you only the results this time: 
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"Add some buttons to the RowColumn." 

1 to: 42 do: [:i | 
i < 32 

ifTrue: [ 

aButton := aRowColumn 
createLabel: 'button' 
ar g B1o c k: nil, 
aBuoton 

labelstring: i printstring ] 
i f F a 1 s e : [ 

aButton := aRowColumn 
createLabel: ' button' 
argB1ock: nil. 
aButton 

labelstring: ' ']. 

aButton manageChi1d]. 

Save the method and run the example. It looks good. Now that we 
have the basic calendar worked out, let’s return to our design goals. In 
our future exploration of this class, we don’t want simply to rummage 
around. We have three specific questions in mind based on our earlier 
exploration of the class Date in a workspace: 

m How can we find and select a date? 

m How can we change the color of a holiday or other important date? 
m How can we control the positioning of the calendar and the month 
start and end points? 


Dealing with Date Selection 

With these goals in mind, let’s do a little thinking. We already know how 
to access the widgets in a rowColumn form through its children collec¬ 
tion, so we should be able to detect a particular date using the Collec¬ 
tion method detect:. Once it is detected, we can change the color by 
setting the foreground color with the widget’s foregroundColor: method. 

Let’s create some code to test this idea. We’ll add the code to our 
existing method so as not to trash the class any more than we have to. 

We’ll call the new method highLightCalendar . This method will select 
a label widget based on its label and highlight it green. We’ll use today’s 
date to test the code. Here is the code to be added to the end of the 
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method (don’t forget to put a period at the end of the last line before you 
add the new code): 

(aRowColumn children detect: [:c | c labelString= Date today dayOfMonth 
printString]) 

foregroundColor: (CgRGBColor red: 0 green: 65535 blue: 0). 

Some explanation is in order. First, the children method answers the 
children of a widget. Second, the detect: method searches a collection 
and answers the first object it finds that matches the condition set in the 
block. Third, the CgRGBColor class will be covered later. The code used 
here results in the color green being assigned as the foreground color of 
the widget. Ready for a test? Save the method and run the example. 

Ah, sweet success. That was easy. Now on to the last goal, positioning 
the widgets so they look more like a calendar. The columns will repre¬ 
sent the weekdays starting with Sunday, so we want the calendar to be 
blank up to the first of the month, then blank after the last day of the 
month. The only tricky thing here is controlling where we start and end 
the labeling of widgets. If we think of the collection of labels as an array 
and the day of the week as an index into the array, we can start our 
month on any of the first line’s columns. This sounds good. Let’s modify 
our workhorse method once more to test our theory. 

Again we will work with Bate class methods. This time we need the 
instance methods firstDayOfMonth, daylndex , and daysInMonth, as well 
as today. There is one problem: The daylndex method is based on Mon¬ 
day, not Sunday, like we need, so we will have to pad the index a little. 
The best place to add our code is around the existing loop that creates 
the widgets. Here is the new loop: 

"Add some buttons to the RowColumn." 

theDate := Date today. 

start := theDate firstDayOfMonth daylndex - 1. 

end := theDate daysInMonth + 1. 

1 to: 42 do: [:i | 

((i - startX end and: [i >start]) 
ifTrue: [ 

aButton := aRowColumn 
createLabel: ' button' 
argBlock: nil. 
aButton 

label String: ( i - 


start) printstring ] 
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i f F a 1 s e : [ 

aButton := aRowColumn 
c reateLabel: ' button' 
argB1ock: nil. 
aButton 

1 :ibe1String: ' ' ]. 
aButton manageChi1d]. 

Be sure to replace the Date today reference in the second-to-last line 
of the method with the new variable theDate and to add the new tempo¬ 
rary variables to the method definition. 

With all our goals met, we can move from exploration to develop¬ 
ment. In our exploration, we learned about the Date class and found 
some very useful methods that we have put to good use. We also worked 
with an existing example application and modified it to meet our needs; 
we ended up with some code we hope to be able to use in our final 
application. Along the way we were introduced to some magic tricks we 
can perform with the assistance of inspectors, as well as some of the 
powerful features of the browser. For your scrap book, here is one last 
look at the complete method and the resulting window (see Figure 7-6): 

createWorkRegion 

"Private - Create the receiver's workRegion 
widget hiera rchy . " 

| aRowColurrm aButton dashes theDate start end | 

"Create the RowColumn." 

self rowColumn: 

(aRowColumn := self mainWindow 
createrowColumn: 'RowColumn' 
a r g B1o c k: nil). 

a RowColumn 

marginHeight: 5 ; 
m a r g i n W i d t h : 5 ; 
numColumns:6 ; 

orientation: XmHORIZONTAL; 
packing: XmPACKCOLUMN ; 
radioBehavior: true; 
adjustLast: false. 
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"Add some buttons to the RowColumn." 
theDate := Date today. 

start := theDate firstDayOfMonth daylndex - 1. 
end := theDate daysInMonth + 1. 

1 to: 42 do: [: i | 

((i - startX end and: [i >start]) 
ifTrue: [ 

aButton := aRowColumn 
createLabel : 'button ' 
argBlock: ni1 . 
aButton 

labelstring: ( i - start) 
printstring ] 
i f F a 1 s e: [ 

aButton := aRowColumn 
createLabel: ' button' 
argB1ock: nil. 
aButton 

labelstring: ' ']. 
aButton manageChiId]. 
aRowColumn manageChild. 

self workRegion: aRowColumn. 

(aRowColumn children detect: [:c | c labelstring = theDate 
dayOfMonth printString]) 

foregroundColor: (CgRGBColor red: 0 green: 65535 blue: 0). 


CwRowC oliittin Ena m jzi 


Orientation Packing 
Radio Children 


1 2 3 

4 5 6 7 8 9 10 
11 12 13 14 15 17 
18 19 20 21 22 23 24 
25 26 27 28 29 30 


i A last look at the Calendar example 
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Defining the Calendar Class 

At the heart of our application will be a class that encapsulates the be¬ 
havior of a calendar as we’ve defined it. Moving past exploration, our 
first coding act will be to define class Calendar. What will instances of 
this class need to know and what must they do? 

Class Knowledge 

From our description of what the application will do, we can conclude that 
the class Calendar will need to keep track of several pieces of information: 

h Today’s date (so it can quickly jump back to today on demand) 
m The date currently being displayed 

m The currently displayed month, as a name (for the window label) 

m The cur rently displayed year (also for the window label) 

m Important dates to be highlighted 
h Holiday!) 


All instances of the class Calendar will have the same holidays in our 
scheme (since we aren’t creating a commercial product). This fact makes it 
possible for us to store the holidays in a class variable. Other pieces of 
information a Calendar object needs will be instance variables, since each 
will have values that vary depending on the instance of the class involved. 


Class Behavior 

The list of things a Calendar object must know how to do is short but 
impressive. So far, we’ve identified the following behaviors: 


n Display a calendar. 

■ Allow the user to navigate by month or year. 

■ Highlight special dates in color. 

m Move quickly to the current date. 

» Accept a user-entered date and display the calendar for that month 
with the entered date highlighted. 

This list of behaviors doesn’t include the initialization methods that 
we expect for all classes we create. 
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Class Definition 

There is an application file called SmplePIM.App that contains not only 
the definitions but all the methods as well. You may wish to file in this 
application file, rather than in the template, if you’d rather not type the 
code yourself. Fileln works only if an application in the Loaded Applica¬ 
tions list has been selected. 

Browse SimplePIM and turn on the Show Classes option. Then select 
Browse Class from the Transcript Smalltalk tools menu. This will put 
you into a class browser on the Calendar class. From here you can add 
the changes as we describe them. Also leave an applications browser 
open to export the application from time to time. When exporting, be 
sure to use the name MyPIM.app so you don’t write over the existing 
application or template. 

The code for the class definition is as follows: 

Object subclass: #Calendar 

instanceVariableNames: 'today month monthName day year date ' 
classVariableNames: 'Holidays ' 
poolDictiona ries : ' ' 

Let’s focus for a short time on the more routine behavior of the class. 

initialization Routines 

To create a new Calendar object, we will need to create a class method. 
Here is the code for the new class method: 

new 

"Answer a new Instance of the receiver" 

A super new initialize 

This is a standard method that creates a Calendar object and sends it 
the initialize method, which we’ll discuss next. As with all objects, we 
need to initialize Calendar’s instance variables. These variables deal, 
for the most part, with date-related information. We know that when¬ 
ever the application moves to a different date we must reinitialize the 
values of these variables. So we break the initialization routine into two 
instance methods. Here’s the first: 



CHAPTER 7: A CALENDAR 


131 


initialize 

"initialize the calendar objects" 
today := Date today, 
self setNewDate: today. 

As you can see, this method initializes a Calendar object to deal with 
the current date. Here’s the setNewDate: method called by initialize : 

setNewDate: a Cate 

"Parses a D a t e into my in s t v a r s" 
month := aDate monthlndex. 
monthName := aDate monthName. 
year :« aDate year, 
day aDate dayOfMonth. 

date ■:■** Date today year: year month: month day: day. 

In a later section we deal with the window display of the calendar. 
Let’s move on to the real functionality of the application. 

Incrementing and Decrementing Months and Years 

As users move through a Calendar, we want them to be able to navigate 
a month or year at a time, forward or backward. These four functions 
call for four methods, which we’ll reproduce here and discuss at the end 
of the listings: 

incrementMonth 

"increase month by one" 
month := month + 1. 

month > 12 ifTrue: [ month := 1. year := year + 1]. 
monthName := Date nameOfMonth: month. 

decrementMonth 

"decrease month by one" 
month := month - 1. 

month < 1 ifTrue: [ month := 12. year := year - 1]. 
monthName := Date nameOfMonth: month. 

incrementYea r 

"increase year by one" 
year = 2100 
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ifFalse: [year := year + 1]. 

A year 

decrementYear 

"decrease year by one" 
year = 1901 

ifFalse: [year := year - 1]. 

A year 

Notice that incrementMonth doesn’t loop through a single year but 
continues into the next year. This approach makes writing decrement- 
Month trivial. 

By the way, the limits of 1900-2100 that we set in the incrementYear 
and decrementYear methods are arbitrary. We need a boundary condi¬ 
tion to test for, but feel free to change these if you need calendars that go 
beyond those limits. 

Highlighting Todays Date 

Now let’s write the method that determines whether today is in the cur¬ 
rent month and year calendar: 

showToday 

"answer true if today is in current month and year" 

A ((today monthName = monthName) and: [today year = year]) 

The only executable line of this method checks to see if the monthName 
instance variable matches the monthName that corresponds to today’s 
date and if the year instance variable also matches the year associated 
with today’s date. 

Dealing with Holidays 

As indicated earlier, Holidays is a class instance variable. We therefore 
need a class method to initialize this variable. What kind of data struc¬ 
ture should we use for holidays? We want the list of holidays to prohibit 
the inclusion of the same date twice. An instance of Set seems suited to 
the task, so we’ll use one: 
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newHolidays 

"create a new class holiday Set" 

A Holidays := Set new. 

We need to retrieve the contents of this Set, so we’ll create a class 
method called holidays that simply returns the value of the class vari¬ 
able Holidays : 

hoiid a y s 

"answer the Holidays collection" 

Holidays is Nil 

ifTrue: [ self newHolidays]. 

A Hoiidays 

This method checks whether Holidays has been initialized and, if not, 
initializes it with the newHolidays method. The first time a new instance 
of Calendar needs to work with holidays, if a Set named Holidays hasn’t 
yet been created, we will create one. This is called lazy initialization, 
since it allows the fact that the variable is accessed to initialize it instead 
of initializing directly. Unlike instance variables, class instance variables 
are not initialized by the class. Furthermore, an initialize message does 
not work for a class since its one and only instance is created when it is 
defined. Direct initialization requires you to initialize the class instance 
variable when the class is first used. Since this is difficult to determine, 
lazy initialization is easier and preferred. 

Now we need some way for the user to indicate that a date is a holiday 
so that we can add it to the class variable and be sure it is highlighted 
when displayed. 

add Hoiiday: a Date 

"add a aDate to the Holidays Collection. Uses Time day format" 
A self holidays add: aDate. 

This code will accept a date created with Date today or Date 
newDay:month:year:, but this does not seem like a very friendly way to 
create a date. How would the user expect to enter the date for a new 
holiday? The user will probably want to enter a string like “December 
25,1994” or a date like “12/25/94” or even a European-style date of “25 
Dec 1994.” 
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Unfortunately, Date does not include a method to enter a date as a 
string. Such a method would seem to be quite useful, and we do have a 
pretty good background with dates. Maybe we could create a class method 
that would accept strings. 

A Little Side Trip Bark to the Date Class 

The method needs to identify and separate the useful elements of the 
string that make up a date, then create a new date using the Date class 
method newDay:month:year:. The first part of the task is known as pars¬ 
ing. Parsing will compose the major portion of this method. We should 
find our exploration of methods useful for parsing in the String class. 
What we are looking for are methods that will help us break up a string 
into smaller parts. 

To aid us in our search, we will use another powerful feature of the 
browser. Normally, the browser displays only the methods associated 
with a given class, but through the use of filters we can see the methods 
inherited by a class as well. Open a new classes browser and find the 
String class. In the “Instance Methods” list, select the pop-up choice 
Inheritance, then “From Root - 1.” The list now contains all methods 
inherited by the String class up to the Collection class. We can now 
search all the methods in Collection and its subclasses at once. 

There are many methods to choose from, but the most promising 
methods appear to be substrings and substrings:. These methods break 
a String instance into an array of substrings. The only problem with the 
first method is that it uses spaces to parse the string. This approach will 
work for the month name-based date format but not for the numeric- 
based date format. The second form breaks up a string based on the 
supplied argument. This is better, but it restricts the delimiter to a single 
predefined character. It would seem friendly to allow any non-alphanu- 
meric character as a delimiter. That way, the user could use dashes as 
well as slashes. 

What we need is a way to detect a delimiter and replace it with a 
space. Then we could use the substrings method. We know collections 
can detect objects; we used this method earlier when were setting the 
foreground color of label widgets. How about replacing elements of a 
string? Let’s focus on this aspect for now. 

Again, Smalltalk is rich with methods for copying or replacing ele¬ 
ments of a collection. Copying and replacing seems right, so we will nar¬ 
row our search to methods that do both. There are four methods whose 
names begin with “copyReplac.” Two of these methods, copyReplace- 
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All:ivith: and copyReplacing:withObject: , appear adequate to the task. 
The first replaces a collection with a collection, and the latter will accept 
a single object, such as a char. We could use the latter method along 
with detect: since detect answers a single object, in our case a char. 
While the prospect seems unlikely, if the user used two different delim¬ 
iters, this scheme would fail. 

What we need is a way to select all the delimiters, then replace each 
one with a space. There is a method called select: that selects an ele¬ 
ment of a collection if it meets a supplied condition. That sounds like a 
reasonable approach, but what would we do with our collection of de¬ 
limiters? The copyReplacing:withObject: method can only replace one 
character at a time. We need it to replace more than one. We could put 
the method inside a loop with the delimiter elements as arguments. A do 
loop would work, and the do: method is just right for the job. 

We seem to have all the cast members for our method except the one to 
determine if a character is a delimiter. It’s time to check out the Character 
class instance methods. You can do this quickly with a menu choice find. 

There is a method for checking for alphanumeric characters called 
isAlphaNumeric, but there isn’t one that checks for non-alphanumeric 
characters. lYo problem. We can use not after the isAlphanumeric method 
to invert its logic. Better yet, instead of select: we’ll use reject: — the 
exact opposite of select:. 

We are almost ready to write some code. First, we have to make sure 
this method is part of our application. We do this by indicating we want 
to extend a class. Close the classes browser and return to the applica¬ 
tions browser. Select the class Object (actually, any class will do) and 
from the pop- up menu choose Add... and Extension. Select the Date class 
from the resulting list dialog. You will see that our application classes 
now include the Date class. Our new method will be a Date class method, 
so select Date and make sure the method list is set to “Class Methods.” 
Here is the parser portion of the method called fromString: that we will 
create in class Date:. 

aString := aDateString. 

dels := aDateString reject: [:i | i isAlphaNumeric]. 
dels isErrpty ifTrue: [ A self error: ' Improper Date Format'], 
dels do: ]:d | aString := aString copyRepl aci ng: d withObject: $ ]. 
array := aString substrings. 

Be sure to put a space after the dollar sign on the fourth line. The 
results are almost exactly as planned, with the exception of a check for 
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no delimiters, which results in an error being signaled. Once the delim¬ 
iters have been replaced with spaces, we then use the substrings method 
to convert the string into an array. 

Now that we have the array, we need to assign its elements to our 
variables and make sure the year is in the long year format. Here is the 
code segment for these actions: 

iteml := array at: 1. 

item2 := array at: 2. 

year : = (array at: 3) asNumber. 

year < 100 ifTrue: [ year := year + 1900]. 

Next we need to test the elements of the array by looking for a month 
name instead of a number. Since the month name can be either the first 
or second array element, we will need to check for both. Once we’ve 
made that determination, we simply use the newDay:month:year: method 
to create a new date. Here is the code for this next section: 

iteml first isLetter ifTrue: [" Dec 1, 1994 format" 
month := Date match: iteml asSymbol. 

A s e 1 f 

newDay: item2 asNumber 
month: month 
year: year]. 

item2 first isLetter ifTrue: [ "1 Dec 1994 format" 
month := Date match: item2. 

A sel f 

newDay: iteml asNumber 
month: month 
year: year]. 

We use the Date class method match:, the nice little utility we saw 
earlier, to get the full month name. 

All that is left to do is to handle the all-numeric format. The other tests 
eliminated all possible formats except this one, so it is a simple matter of 
creating the date using the alternate format of this method, which accepts a 
month index instead of a name. Here is the complete method: 

fromString: aDateString 

"Answer a Date taken from aDateString. The format 

of the aDateString can be Dec 1, 1994, 1 Dec 1994 or 12/01/94. 
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Month names can be any size and case. 

Year can be short or long. There must at least two delimiters. 
Delimiters may be any combination of non-alphanumeric characters" 

| iteml item2 month year array dels aString| 
aString : = aDateString. 

dels := aDateString reject: [:i | i isAlphaNumeric]. 
dels isEmpty ifTrue: [ A self error: 'Improper Date Format’], 
dels d o : [: :1 | aString : = aString copyRepl aci ng : d withObject: $]. 
array := aString substrings, 
iteml := array at: 1. 
item2 := array at: 2. 
year := (array at: 3) asNumber. 
year < 100 ifTrue: [ year := year + 1900]. 
iteml first: isLetter ifTrue: [" Dec 1, 1994 format" 
month : = Date match: iteml asSymbol. 

A sel f 

newDay: item2 asNumber 
month: month 
year: year]. 

item2 first: isLetter ifTrue: [ "1 Dec 1994 format" 
month : = Date match: item2. 

A s e 1 f 

newDay: iteml asNumber 
month: month 
year: year]. 

A sel f 

newDay: item2 asNumber 
monthtndex: iteml asNumber 
year: year. 

Except for the lengthy comment, all is as expected. We should test our 
new utility and include some bizarre formats: 

Date fromStrirg: 'Dec 1, 1994'. 

Date fromStrirg: '1 Dec 1994'. 

Date fromStrirg '01/02-94' . 

Date fromStrirg: '01/25-*&(94)' 

Date fromStrirg: 'Dec 1, ''94'. 

Neither comma nor excess delimiters, not even an extra quotation 
mark, will keep our utility from creating the proper date. Now back to 
the Calendar class. 
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Returning for the Holidays 

Using our new method, we can now create a method that allows the user 
to enter a holiday as a string. Based on the addHoliday: method we added 
earlier, here is the new method: 

addHolidayFromString: aDateString 

"add a aDate to the Holidays Collection. Uses Date 
fromString: format" 

A self holidays add: (Date fromString: aDateString) 

The process is easy once you have the right utility method. Once the user 
has defined one or more holidays, we want to highlight them in red. To do 
so, we need to look at the month and year currently displayed and the date 
currently highlighted and determine if any holidays fall within the month 
now displayed. This requires us to generate a date from the currently se¬ 
lected date on the Calendar and compare it against holiday dates. 



This is m instance method, not a class method. 


ma keNewDate 

"create a new date from my date elements" 

A date := date year: year month: month day: day. 

This gives us a point of reference. We can now use this method in 
another method that will answer a collection of holidays in the current 
month and year calendar: 

showHol1 days 

"Answer a collection of holidays that fall In the current month" 

| aCol1ectlon | 

aCollectlon := OrderedCol1ectlon new. 

self makeNewDate. "Sync current date with other variables" 
self class hoi 1 days do: 

[: each | ( each monthlndex = month ) IfTrue: 
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[ aCollection add: each ] 

]. 

A a C o 11 e c 1: i o n 

Notice that we use the monthlndex method from our exploratory pro¬ 
gramming to get the number of the month as a valid value for compari¬ 
son. We also need a method to answer the current date, which we will 
call date. The code follows: 

date 

"answer a new date" 

A self mekeNewDate. 

We simply answer the result of the method makeNewDate. 

Creating the Calendar Application 

We have now defined a useful Calendar object, but nobody else can use 
it yet, since it lacks a user interface. You know from Chapter 6 that this 
interface is provided by an application object built around an object like 
Calendar. In this section we’ll build the application. We’ll name it 
CalendarWindow. 

To refresh our memories, a Smalltalk application must fulfill certain 
obligations: 


■ Remember its current state. 

■ Create panes. 

■ Provide the contents of a pane. 

n Carry out communications and synchronization. 
m Define menus for the pane. 


Our application needs to keep track of three things: its Calendar ob¬ 
ject, the window, and the form it will use to display the calendar. The 
object definition, therefore, will include instance variables called calen¬ 
dar , shell, and dates. 

The application needs to know how to define and open a window with 
a rowColumn form. We can use the open method from the Counter appli¬ 
cation and the createRegion method we created during our exploration 
of the CwRowColumnExample class to give us a start on these processes. 
We will need to define menus or buttons or both to permit the user to: 
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m Increment or decrement the month and year. 
m Display today. 
m Find a specific date. 


Hie Object Definition 

We will subclass the class Object to define our new Calendar Window 
object. Here is its class definition: 

Object subclass: #CalendarWindow 

instanceVariableNames: 'dates calendar shell weekdays ' 
classVariableNames: '' 

poolDictionaries: 'CwConstants CgConstants' 


The Open Method 

Figure 7-7 shows how we’ve designed the window in which Calendar- 
Window displays its calendar. We’ve adopted a convention from hypertext 
navigation programs, in which a single left angle bracket serves as a 
symbol of a left arrow and moves the display back the smallest incre¬ 
ment (in this case, a month). Similarly, a right angle bracket stands for 
“display the next month.” The two buttons with two angle brackets in 
them move by year. 

Here is the open method that builds the window. Most of this code is 
familiar. The few lines requiring further comment are explained follow¬ 
ing the listing: 


September 1394; 




Calendar 


< l« 


Today 


»( > 


Figure 7-7. 


The window for the 8‘amplePIfV! Calendar application 
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open 

"open a Calendar on today's date" 

| main form text rowColumn | 
shell := CwTopLevel She11 

createApplicationShel1: 'Calendar Example' 
a r g B1 o c k: nil. 
main := she'1 

createMainWindow: 'main' 
argB1ock: nil. 
main managed hi Id. 
form := main 

createForm: 'form' 
a r g B 1 o c k: nil. 
form manageChi1d. 

shell realizeWidget. 

The code for this window was taken from the top portion of the 
CounterWindow method we developed in Chapter 5. We don’t need the 
button or the text widget from that method, so we didn’t include those in 
the code. 

We will adapt the modular region methodology we found in the CwRow- 
ColumnExample class. This keeps the open method small and concen¬ 
trates the work of creating each region in its own method. 

We will need four regions. The table below list the type, function, and 
method name for each of the regions: 


| TYPE 

lifi™ 

METHOD NAME 

Dates 

Displays the date labels 

addDatesRegion: 

Weekdays 

Displays the weekday name labels 

addWeekdaysRegion: 

Buttons 

The five navigation buttons 

addButtons: 

Menus 

IV enu equivalents for navigation buttons 

addMenuBar: 


We will start with the addDatesRegion: method, which we can create 
from the createWorkRegion: method we worked on in the CwRowColumn- 
Example class. To refresh your memory, here is that method: 
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createWorkRegion 

"Private - Create the receiver's workRegion 
widget hierarchy." 

| aRowColumn aButton dashes theDate start end | 

"Create the RowColumn." 
self rowColumn: 

(aRowColumn := self mainWindow 
createRowColumn: 'RowColumn' 
argBlock: nil). 
aRowColumn 

marginHeight: 5; 
marginWidth: 5; 
numColumns:6; 

orientation: XmHORIZONTAL; 
packing: XmPACKCOLUMN; 
radioBehavior: true; 
adjustLast: false. 

"Add some buttons to the RowColumn." 
theDate := Date today. 

start := theDate firstDayOfMonth daylndex - 1. 
end := theDate daysInMonth + 1. 

1 to: 42 do: [ : i | 

((i - startX end and: [i >s ta rt ]) 
ifTrue: [ 

aButton := aRowColumn 
createLabel: 'button' 
a rg B1ock : nil. 
aButton 

labelstring: i printstring ] 
i f F a 1 s e : [ 

aButton := aRowColumn 
createLabel: 'button' 
argBlock : ni1 . 
aButton 

1abelString : ' ' ] . 

aButton manageChiId]. 
aRowColumn manageChild. 
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self workRegion: aRowColumn. 

(aRowColumn children detect: [:c | c labelstring = theDate dayOfMonth 
p ~i ntStri ng]) 

foregroundColor: (CgRGBColor red: 0 green: 65535 blue: 0). 

One thing we should consider is whether we should use this method 
or scatter the code around to multiple methods. This decision should be 
based on code reuse and readability. Where else would such a code seg¬ 
ment be useful? 

For example, consider the loop that creates, labels, and positions the 
label widgets. It’s unlikely we will want to recreate the widgets or repo¬ 
sition them without restarting the application, but labeling is something 
we intend to do often, so we need to move this code into a separate 
method. While this sounds good, the reality is that labeling is integrated 
into the existing loop, so we may need to duplicate some code. Here is a 
first cut at the segment to be used in the addDatesRegion: method: 

"Add some battons to the RowColumn." 

1 to: 42 do: [:i | 

aButton := aRowColumn 
createLabel: 'button' 
a r g B1o c k: nil. 
aButton manageChi 1 d]. 

aRowColumn manageChi1d. 

self updateCalendar. 

As you can see, we are left with a very simple loop that simply creates 
42 labels. The hard work has been moved to a new method we will call 
updateCalendar. This method will be called whenever we want to up¬ 
date the calendar with a new month display. The changes that need to 
be made focus on accessing the rowColumn object and its buttons. Since 
this method will be separate from the object’s creation method, we can 
no longer use the temporary variable for assignment. Instead, we will 
use the dates instance variable we defined earlier. To gain access to the 
buttons, we will once again rely on the children method. Here is the code 
segment for this method (we have italicized the code that is in both meth¬ 
ods’ segments, and we have boldfaced new code): 

theDate := Date today. 

start := theDate firstDayOfMonth daylndex - 1. 

end := theDate daysInMonth + 1. 

1 to: 42 do: [:i | 
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aButton := dates children at: | 

((i - startX end and: [i >start]) 
ifTrue: [aButton 

1abelString:(i-start) printstring ] 
ifFalse: [aButton 
labelstring: ' ']. 

]. 

(dates children detect: [:c | c labelstring = theDate 
dayOfMonth 
printString]) 

foregroundColor: (CgRGBColor red: 0 green: 65535 blue: 0). 

Only the code that starts and ends the loop is reproduced in each of the 
segments, and, except for one added line of code, all the code came from 
the original createWorkRegion: method. That’s pretty good code reuse. 

To finish the addDatesRegion: method we need only add the top part 
of the original method to this method and name it. This added part is 
unchanged except for an added assignment of the form to our dates 
instance variable The updateCalendar method needs only a name. Here 
are the new methods in the recovery room after surgery: 

addDatesRegion: form 

"Private - Create the receiver's Dates region 
where the date labels are displayed." 

| aRowColumn aButton dashes | 

"Create the RowColumn." 

(dates := aRowColumn := form 

createRowColumn: 'RowColumn' 
argBlock: [:w | w 
marginHeight: 5; 
marginWidth: 5; 
numColumns: 6; 
orientation: XmHORIZONTAL; 
packing: XmPACKCOLUMN; 
entryAlignment: XmALIGNMENTEND; 
radioBehavior: false; 
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adjustLast: false; 
spacing: 7]). 

"Add some buttons to the RowColumn." 

1 to: 42 do: [: i | 

aButton := aRowColumn 

createLabel: ' button' 
argBlock: nil. 
aButton manageChiId]. 

aRowColumn manageChild. 
self updateCalendar. 


updateCalendar 

"Display a calendar for the current date" 

| theDate aButton start end reply monthName year | 
theDate := Date today. 

start := theDate firstDayOfMonth daylndex - 1. 
end :=theDate daysInMonth + 1. 

"Add some buttons to the RowColumn." 

1 to: 42 do: [:1 | 

aButton := dates children at: i. 

((i - startX end and: [i >start]) 
ifTrue: [ 

aButton labelstring: ( i -start) printstring. 

] 

ifFalse: [ 

aButton labelstring: ' ']]. 

(dates children detect: [:c | c labelstring = theDate 

dayOfMonth printstring]) 

foregrounded or: (CgRGBColor red: 0 green: 65535 blue: 0). 

Our earlier explorations have proved quite fruitful. As you may have 
guessed, we will be visiting this method again in the future. 

Next in our window creation efforts is the development of a method to 
display the weekday names of each month. Since these labels will not be 
changing from month to month, we need only one method to create and 
label them. The method will be similar to the addDatesRegion: method 
we just created, so we will use that method as a starting point for this 
one. Select the addDatesRegion: method, rename it to addWeekdays- 
Region:, and save it. 
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We will use a rowColumn widget for this region, so we need only change 
the code related to individual attributes of this widget. We thus save 
quite a bit of work. We need 7 columns, VERTICAL orientation, CENTER 
alignment, a spacing of 4 and a new attribute, entryBorder, with an ini¬ 
tial value of 1. The last attribute controls whether we get a border around 
the labels. Our extensive survey of users found this to be desirable, so 
we include it here. Make these changes and save the method. 

Now for the unique aspects of this method. We again need to assign 
the form to an instance variable, this time weekdays. Also, the current 
loop iterates through integers, but this just won’t work for weekday 
names. We need to change the loop so that it works with an array of 
strings. This change is actually easy if we use an array constant filled 
with the label strings as the receiver for the do loop. Here is the recon¬ 
structed method: 

addWeekdaysRegion: form 

"Private - Create the receiver's WeekDays region 
where the weekday name labels are displayed." 

| aRowColumn aButton buttons | 

"Create the RowColumn." 

(weekdays := aRowColumn := form 
createRowColumn: 'weekdays' 
a rgB1ock : [:w | w 
marginHeight: 5; 
marginWidth: 5; 
numColumns: 7 ; 
orientation: XmVERTICAL; 
packing: XmPACKCOLUMN ; 
entryAlignment: XmALIGNMENTCENTER; 
radioBehavior: false; 
adjust Last: false; 
spacing: 4; 
entryBorder : 1 ]) . 

"Add some buttons to the RowColumn." 

#( ' Su’ 'H' ■Tu' 'W' 'Th' 'F' 'Sa') do: [:i | 
aButton := aRowColumn 


createLabel: 'button' 
a r g B1o c k: nil. 
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aButton label String: i . 
aButton manageChi1d]. 

aRowColumri manageChild. 

We will reserve the menu adding method until later, so we need only 
the addButtons: method to complete our modular open method design. 
This method has nothing in common with the two other methods, so we 
will have to start with a blank template. For this method, we need to 
deal with callbacks, since these buttons will respond to user input. We 
will also need to position these buttons manually, since the geometry 
management we’ve come to rely on will not let us leave the gaps we 
want around the Today button. Here is the code to create the first button 
and its callback: 

month'\head := form 

createPushButton: ' > ' 
argBlock: nil. 

monthAhead addCal1 back: XmNactivateCal1 back 
r e c eiv e r : self 

selector: #monthAhead:clientData:callData: 
clientData: nil. 
monthAhead manageChild. 

Except for their labels and callback method names, the code for the 
other four buttons is exactly the same. We’ve named the methods the 
same as the buttons to help avoid confusion. 

The tricky part is next. Now we have to handle the button attach¬ 
ments to end up with the four arrow buttons tight against the left and 
right sides of the forms widget, and with the Today button centered and 
offset between them. We could use (x,y) positioning and “hard code” the 
buttons into place, but let’s look at using geometry management. The 
attachments will be to one another and to the form. We’ll work left to 
right, so we’ll start with the monthBack button. Here is the code for a 
segment that can be added at the end of the method: 

monthBack 

topAttachment: XmATTACHFORM; 

1eftAttachment: XmATTACHFORM. 

This button is attached at its top and left to the form. Why only these 
two sides? Because if we attached the bottom and right sides to the form, 
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the button would stretch and occupy the entire form. Next is the yearBack 
button, which will attach to the form and to the monthBack button. The 
code follows: 

yearBack 

topAttachment: XmATTACHFORM; 

1eftAttachment: XmATTACHWIDGET; leftWidget: monthBack. 

The Today button is a little bit more difficult since it needs to attach to 
the yearBack button and leave a gap between the buttons. We will use 
the offset attribute to provide the spacing; again, here is the code: 

today 

topAttachment: XmATTACHFORM; 

1eftAttachment: XmATTACHWIDGET; leftWidget: yearBack; 

leftOffset: 20. 

The next two buttons follow the same pattern, so we’ll show you the 
call for both of them: 

yea rAhead 

topAttachment: XmATTACHFORM; 

1eftAttachment: XmATTACHWIDGET ; leftWidget: today; 

leftOffset: 20. 

monthAhead 

topAttachment: XmATTACHFORM; 

1eftAttachment: XmATTACHWIDGET; leftWidget: yearAhead. 

That completes these methods. 

We are almost ready for a smoke test, but before we add these new 
methods to open, we need to deal with the positioning and attachment of 
the two rowColumn widgets. Attaching these widgets to the form is not 
enough, since by default they would occupy the same space, and we all 
know that two objects cannot occupy the same space. (Well, at least they 
can’t be visible at the same time.) So we need to attach them to each 
other as well. We’ll start with the weekdays region, since it will be the 
form attached under the buttons. 

Which button shall we attach to? The most logical choice would be 
the Today button, since it is in the center. A small problem is raised by 
this decision: How do we gain access to this button object to attach to it? 
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The two rowColumn widgets have been assigned to instance variables 
so we can easily access them, but not so the buttons. 

It looks like a job for the detect: method once again. In this scene, the 
method will quickly go out to the form and search its children for a 
widget labeled “Today.” Once the object is found, it will return the object 
so we can attach to it. Here is the code segment to be added to the bot¬ 
tom of the addWeekDaysRegion: method: 

buttons := form children detect: [:c | c labelstring = 'Today']. 
aRowColumn setValuesBlock: [:w | w 

topAttachment: XmATTACHWIDGET; topWidget: buttons]. 

Next, we attach the dates region rowColumn widget to the weekdays 
region rowColumn widget. No detection required this time, we simply 
use the instance variable. Here’s the code to be added to the addDates- 
Region: method: 

aRowColumn secValuesBlock: [:w | w 

topAttachment: XmATTACHWIDGET; topWidget: weekdays; top0ffset:0; 
bottomAttachment: XmATTACHFORM; 

1eftAttachment: XmATTACHFORM; 
rightAttachment: XmATTACHFORM]. 

Here we make sure the widget occupies the remaining area of the 
form by attaching the other three sides of the widget to the form. 

We must next outfit the open method with calls to the other methods. 
We want the methods called in the same top-down order we want the 
regions displayed in. Here is the open method thus far: 

open 

"open a Calendar on today's date" 
j main form text rowColumn | 
self setup. 

shell := CwTopLevelShel 1 

createApplicationShel1: 'Calendar Example' 
a r g B1o c k: nil. 
main := shell 

createMainWindow: 'main' 
a r g B1 o c k : nil. 
main manageChild. 
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form := main 

createForm: 'form' 
argBlock: ni 1 . 
form manageChlld. 

self addButtons: form, 
self addWeekdaysRegion: form, 
self addDatesRegion: form. 

shell realizeWidget. 

Get your fire extinguisher ready—it’s time for the smoke test. Enter 
the following into a workspace, select it, and Execute it: 

CalendarWindow new open. 

No fire, not even a puff of smoke. It looks good. We are ready to wire 
it up and paint it. With a successful test under your belt, remove the test 
code in the updateCalendar method we created earlier. 

Configuring Updates 

We left the updateCalendar method so that it set the variable theDate to 
today’s date. We actually want to set this variable to the current date of 
the calendar. We have already created an instance method for this pur¬ 
pose in the Calendar class. We simply send this message to the instance 
variable calendar, and we are in business. Here is the code segment for 
the revised updateCalendar (changes are in bold): 

updateCalendar 

"Display a calendar for the current date" 

| theDate aButton start end reply monthName year | 
theDate := calendar date. 

start := theDate firstDayOfMonth daylndex - 1. 
end :=theDate daysInMonth + 1. 

With this small change, we have created the need to assign a cal¬ 
endar instance to the calendar instance variable. We will cover this 
in the next section. 
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The setLaiwi and setUp Methods 

We need two methods: one to initialize the calendar instance variable 
and one to add a month-year label to the window. We will add calls to 
both of these methods to the bottom of the open method. Here’s the code 
for the setUp method that will perform the first task: 

setUp 

"setup the application" 
calendar := Calendar new. 

This method creates a new Calendar object and displays it. 

The other setup method we need is setLabel. Here is what it looks like: 

set Label 

"answer the window label after getting string from calendar 
instance" 

shell tit'e:: calendar monthYearString. 

This method uses a Calendar method called monthYearString that we 
have not yet defined. We will define it next. 

We need to add the setLabel method to the updateCalendar method to 
ensure that the correct month and year will display when we update the 
window. Remember that earlier, when we defined this method, we made 
a mental note to create the missing monthYearString method that it needs 
to work correctly. Here’s the code for that method: 

monthYearStrinq 

"answer a string with the current month and year" 

A monthName,’ ’,year printstring. 

As you can see, this method simply concatenates two pieces of infor¬ 
mation we already have: the name of the month and the year. The only 
tricky part is to make sure the year prints as a string and not as a num¬ 
ber. This is a trivial task in IBM Smalltalk thanks to the built-in printstring 
method that all objects understand. 

We need this method to control access to the Calendar object’s class 
instance variables. We could have added methods simply to answer the 
monthName and year , then built our own string, but this approach is 
more object-oriented in that it leaves data manipulation to the class that 
owns the data. 
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Highlighting Special Dates 

Recall that earlier in the chapter we wrote some code as part of the 
createWorkRegion: method that selected and colored a label widget. Later 
we moved this code to the up date Calendar method. Well, it’s come time 
to uproot this code once more and use it to create our highlight:with: 
method. To jog your memory, here is the segment: 

(dates children detect: [:c | c labelstring = theDate dayOfMonth 
printString]) 

foregroundColor: (CgRGBColor red: 0 green: 65535 blue: 0). 

One thing this code brings to mind is that we have to set the color 
each time we want to use a color. This need could become a pain over 
time, so we’ll create three new class methods for CgRGBColor to create 
these colors for us. 

Adding a Little tiler to the Application 

Select Add, then Class Extensions from the pop-up list, then select the 
CgRGBColor from the resulting list dialog. The class will be added to our 
application. In a blank template, add (don’t forget this is a class method): 

red 

"answer the color red" 

A self red: 65535 green: 0 blue: 0. 

The other two methods are similar: 

green 

"answer the color green" 

A self red: 0 green: 65535 blue: 0. 

bl ue 

"answer the color blue" 

A self red: 0 green: 0 blue: 65535. 


That’s all there is to it. 
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Back to the Highlights 

To be more generic, our new method will have two arguments, the string 
representing the label of the widget we are searching for and the color 
with which to highlight the found widget. Here is the new method: 

highlight: a String with: aColor 

"highlight the date represented by aString with a aColor. " 

| date string | 
string := aString isString 
ifTrue: [ aString] 
ifFalse: [aString printString]. 

date : = dates children detect: [:c | c labelstring = string], 
date foregrounded or: aColor. 

We added some code to make sure we were passed a string and, if not, to 
convert the first argument to a string. This addition allows us to pass inte¬ 
gers and symbols directly to the method without preconverting them. 

Now, let’s write the method that handles displaying and coloring to¬ 
day and holidays. This method will query the Calendar instance to see if 
specific dates need to be highlighted, then highlight any such dates. This 
method will also use our new color methods. Creating a separate high¬ 
light method makes it easier for us to add types of special dates later. 
Remember that our Calendar instance methods returned a Boolean value 
in the case of showToday and a collection in the case of showHolidays. 

highlightCalendar 

"highlight the appropriate dates in the calendar" 

| today holidays| 

holidays := : calendar showHolidays. 

holidays dc: [:h | self highlight: h dayOfMonth with: CgRGBColor 
red]. 

calendar showToday 

ifTrue: [ today := calendar today. 

self highlight: today dayOfMonth with: CgRGBColor green, 
(weekdays children at: today daylndex) foregroundColor: 
CgRGBColor green. 

]. 

If showToday answers true, we know that we are displaying a calen¬ 
dar for this month and year, so we can highlight today’s day in green. 
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Because we used iJTrue: logic, nothing happens if the month and year do 
not match. Likewise, nothing will happen if we use a do: for the an¬ 
swered holidays when the collection is empty. We put today after holi¬ 
days, so if today is a holiday it will still be displayed in green. We added 
one cosmetic change that highlights the weekday label for today’s date, 
a result of additional user surveys. 

A Slight Detour 

We also query the Calendar instance concerning today. This method is 
currently undefined, so before we forget, let’s leave the CalendarWindow 
definition and return to the Calendar class to define an instance method 
called today. (Now aren’t you glad you can open multiple browsers?) 

today 

"answers the date for today" 

A s e1f Initialize 

This is a rather crude way of making the calendar display today’s 
date. We might need to change it in the future if, for example, we were 
to add other initializations to the routine. For the present, though, this 
does the job with a minimum of effort and code. It also seems reason¬ 
able to assume we will need this method somewhere. 

Adding Menu Equivalents to Buttons 

Most software designers believe that a user interface should offer the 
user more than one way to accomplish common tasks. We’ll create a 
menu called Look that will provide the user with menu choices that are 
equivalent functionally to the buttons in the window. This menu is one of 
two in the window. The other is the main Calendar menu that provides 
the user with the ability to refresh the display, go to a specific date, and 
undertake other activities for which there are no buttons. 

How do we hook into the chain of menus? And what is the format for 
a menu (not to mention a submenu)? As you may recall, in IBM Smalltalk, 
menus are created with rowColumn forms and buttons. As a result, we 
can use the same code to create menus that we used earlier to create 
buttons. We need only add some code to create the menu bar, pull-down 
menu, and cascadeButton. We also will not need the button attachment 
code, since attachment is handled automatically for menus. Here is a 
first cut at this method: 
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addMenuBar: aMainWindow 

"Add “he 5 menu buttons to the window" 

| monthAhead yearAhead today monthBack yearBack menuBar form 
subMenu | 

menuBar:=aMainWIndow createMenuBar: 'menu' 
a r g B1oc k: nil. 
menuBar manageChlld. 

form := menuBar createPul1downMenu: ’pulldown’ 
argBlock: nil. 

subMenu:=menuBar createCascadeButton: ’Calendar’ 
argBlock: [:w| w subMenuId: form]. 
subMenu manageChlld. 

monthAhead : = form 

createPushButton: ’ > ’ 
argBlock: nil. 

monthAhead addCal1 back: XmNactlvateCal 1 back 
receiver: self 

selector: #monthAhead:c!1entData:callData: 
cl 1entData : nil. 
monthAhead manageChlld. 

yearAhead := form 

createPushButton: ’>>’ 
argB1ock: nil. 

yearAhead addCal 1 back: XmNactlvateCal1 back 
receiver: self 

selector: #yearAhead:cl1entData:callData: 
c 1 1 e n t; D a t a : nil. 
yearAhead manageChlld. 

today := form 

createPushButton: ’Today’ 
a rg B1ock : nil. 

today addCallback: XmNactl vateCal1 back 
receiver: self 

selector: #today : cl'.i entData : call Data : 
clIentData: nil. 
today manageChl1d. 
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yearBack := form 

createPushButton: '<<’ 
argBlock: nil. 

yearBack addCal1 back: XmNactivateCa11 back 
receiver: self 

selector: #yearBack:clientData:callData: 
clientData: nil. 
yearBack manageChild. 

monthBack : = form 

createPushButton: ' < ' 
argBlock: nil. 

monthBack addCal 1 back: XmNactivateCal1 back 
receiver: self 

selector: #monthBack:clientData:callData: 
clientData : nil. 
monthBack manageChild. 

The format of the method is the same as that of the other region cre¬ 
ation methods. You may have guessed that if we were to run this code it 
would create a menu, but the menu labels would be the same as the 
buttons and in the same order. Also, our design calls for a Look submenu 
for the navigation buttons and for two extra menu items that do not have 
button equivalents. In other words, we aren’t finished with this method. 

The first thing we need to add is the Look submenu. It can be confus¬ 
ing to hook up all the elements of the submenu, so we will take it one 
step at a time. For a submenu we will need two more objects, a second 
pull-down menu and a cascadeButton. You can think of the pull-down 
menu as the rowColumn form to which the menu is attached. The Cascade- 
Button is the button attached to a menu (form). Both objects are created 
by the existing menu (form). Here is the code that must go between the 
existing menu creation code and the button creation code: 

form2 := form createPul1downMenu: 'pu112' 
argBlock: nil. 

subMenu2 :=form createCascadeButton: 'Look' 
argBlock: [:w| w subMenuId: form2]. 
subMenu2 manageChild. 
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The temporary variable called form holds the main pull-down menu. 
Notice that the form first creates both objects, then puts the objects in 
the main pull-down menu. 

Next, we assign the existing buttons to the appropriate menus by 
making sure the correct menu creates the buttons. Right now, all but¬ 
tons are created by the main pull-down menu, but we actually want only 
the Today button created by this object. All other buttons will be created 
by the second pull-down menu held by the variable form2. We also want 
to change the Labels to something more meaningful to the user. Here is 
the button creation segment of code with these changes in bold: 

monthAhead := form2 

createPushButton: ' Month Ahead ' 
argBlock: nil. 

monthAhead addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: //monthAhead :clientData:callData: 
cl i entC'ata : nil. 
monthAhead manageChild. 

yearAhead := form2 

createPushButton: 'Year Ahead’ 
argBlock: nil. 

yearAhead addCallback: XmNactivateCal1 back 
receiver: self 

selectcr: //yea r Ahead : cl i entData : cal 1 Data : 
c1ie n t D a t a : nil. 
yearAhead manageChild. 

today : = form 

createPushButton: 'Go to Today' 
argBlock: nil. 

today addCallback: XmNactivateCa11 back 
receiver: self 

selector: //today:clientData:callData: 
clientData: nil. 
today manageChild. 

yearBack := form2 

createPushButton: 'Year Back' 
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argB1ock: nil. 

yearBack addCallback: XmNactivateCa11 back 
receiver: self 

selector: #yearBack:cl1entData:cal 1 Data: 
clientData: nil. 
yearBack manageChild. 

monthBack := form2 

createPushButton: 'Month Back ' 
argB1ock: nil. 

monthBack addCallback: XmNactivateCa11 back 
receiver: self 

selector: ^monthBack:clientData:callData: 
clientData : nil. 
monthBack manageChild. 

We are almost done. We just need to add two new buttons to the main 
menu, one to go to a specific a date and one to refresh the calendar. This 
step will take no time at all. We’ll simply use the last button creation 
code segment as our template for these two buttons. We will need two 
new temporary variables, gotoMY and refresh. Make sure you change all 
the references to the monthBack variables in the pasted code to these 
variable names, and make sure you create the buttons with form, not 
form2. Here is the finished method: 

addMenuBar: aMainWindow 

"Add the 5 menu buttons to the window" 

| monthAhead yearAhead today monthBack yearBack menuBar form 
subMenu subMenu2 form2 
gotoMY refresh | 

menuBar:=aMainWindow createMenuBar: 'menu' 
argBlock: nil. 

menuBar manageChild. 

form := menuBar createPul1downMenu: 'pulldown' 
argBlock: nil. 

subMenu:=menuBar createCascadeButton: 'Calendar' 

argBlock: [:w| w subMenuId: form]. 

subMenu manageChild. 

form2 := form createPul1downMenu: 'pu112 ' 
argBlock: nil. 
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subMenu2 :-form createCascadeButton: 'Look' 

argBlock: [:w| w subMenuId: form2]. 
subMenu2 manageChild. 

monthAhead := form2 

createPushButton: ' Month Ahead ' 
argBlock: nil. 

monthAhead addCal1 back: XmNactivateCal1 back 
receiver’: self 

selector: #monthAhead:clientData:callData: 
clientData: nil. 
monthAhead manageChild. 

yearAhead := form2 

createPushButton: 'Year Ahead' 
argBlock: n " : 1 . 

yearAhead addCallback: XmNactivateCal1 back 
receiver: self 

selector: #yearAhead:clientData:cal 1 Data: 
clientData: nil. 
yearAhead manageChild. 

today := form 

createPushButton: 'Today' 
argBlock: nil. 

today addCallback: XmNactivateCal1 back 
receiver: self 

selector: #today:clientData:callData: 
clientData: nil. 
today manageChild. 

yearBack : = = form2 

createPushButton: 'Year Back' 
argBlock: nil. 

yearBack addCallback: XmNactivateCal1 back 
receiver: self 

selector: #yearBack:clientData:callData: 
clientData: nil. 
yearBack manageChild. 


monthBack : = form2 
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createPushButton: 'Month Back ' 
argBlock: nil. 

monthBack addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #monthBack:clientData:callData: 
clientData : nil. 
monthBack manageChild. 

gotoMY := form 

createPushButton: 'Go to Month and Year' 
argBl ock: ni 1 . 

gotoMY addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #gotoMonthYear:clientData:callData: 
clientData: nil. 
gotoMY manageChild. 

refresh := form 

createPushButton: 'Refresh ' 
argBlock: nil. 

refresh addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #updateCalendar:clientData:callData: 
clientData: nil. 
refresh manageChild. 

An Extra Update Method 

In the preceding section we created the need for a new method to up¬ 
date the calendar when Refresh is chosen from the Calendar menu. The 
new method is required since we do not have an existing callback method 
for this operation. The new method will just call the existing method. 
Here is the code: 

updateCalendar: aWidget clientData: data callData: moreData 
"refresh the calendar display " 
self updateCalendar 
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Methods to Handle Navigation 

We have identified and named methods for both buttons and menus to 
call to allow the user to navigate forward or backward by month or year 
or to jump to today’s date in the calendar. Now we need to write these 
methods. Fortunately we can use the method we created in the last sec¬ 
tion as a template. 

The method needed to move forward by a month simply uses the 
incrementMonth method we defined in the class Calendar (the life of an 
application object can be quite cushy!): 

monthAhead: aWidget clientData: data cal 1 Data: moreData 
"display next month's calendar" 
calendar incrementMonth. 
self updateCalendar 

Note that we are using the callback naming convention and that we 
ignore the arguments passed to the method. By using this convention we 
are saying these methods are public and are callbacks. Since the menus 
and buttons use the same format, we only need one method. 

The methods used to back up a month and move by a year are similar, 
as you’d expect: 

monthBack: aWidget clientData: data cal 1 Data: moreData 
"display previous month’s calendar" 
calendar decrementMonth. 
self uodateCalendar 

yearAhead: aWidget clientData: data cal 1 Data: moreData 
"display next year’s calendar" 
calendar incrementYear. 
self updateCa1endar 

yearBack: aWioget clientData: data cal 1 Data: moreData 
"display previous year’s calendar" 
calendar dec rementYear. 
self updateCalendar 

The only navigation we haven’t dealt with is moving to today’s date. 
We could accomplish this move simply by sending the Calendar object 
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an initialize message directly. This would be bad form, though, because 
only an object should carry out its own initialization. 

To be consistent with the other navigational methods and to keep re¬ 
sponsibilities separate, we’ll define this method to call the today method 
we created earlier. Here is the method for moving to today’s date: 

today: aWidget clientData: data cal 1 Data: moreData 
"display today's calendar" 
calendar today, 
self updateCalendar 


Moving to a Specific Date 

The only capability we haven’t yet implemented in CalendarWindow is 
support for the user’s entering a date or a month-year combination and 
switching to a view of the appropriate month. 

Earlier we created a class method calledfromString for the Date class. 
We should easily be able to modify this method for additional purposes. 
But one major question arises: Should this be another Date class method 
or a Calendar instance method? The way to answer this question is to 
think about the global use of the function for which it is being created. 
This seems like an application-specific utility, not something other ap¬ 
plications would need to use, so we will make the method a Calendar 
instance method. 

To make the method work we need to be able to determine whether 
we are dealing with a month-year format; if not, we will pass the argu¬ 
ment to the Date class method. One thing we know about this format is 
that it will have only two elements, not the three we found in normal 
dates. If the third element is missing, we know we have a month-year 
format. Let’s look at the first few lines of the Date class method fromString 
for a clue as to how to implement this idea: 

aString := aDateString. 

dels := aDateString reject: [:i | i isAlphaNumeric]. 

dels isEmpty ifTrue: [ A self error: 'Improper Date Format']. 

dels do: [:d | aString := aString copyReplacing: d withObject: $ ]. 

array := aString substrings. 

iteml := array at: 1. 

item2 := array at: 2. 

year : = (array at: 3) asNumber. 
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This segment reminds us that we created an array from the input 
string. So if we check the array size, we can determine the number of ele¬ 
ments in the string. Now we have a working plan. Let’s create the method: 

setDateFromString: aDateString 

"Parse aDateString for date or month-year 
then set my inst vars to the resulting date. 

Adapted from Date fromString which is documented as: 

Answer a Date taken from aDateString. The format 

of the aDateString can be Dec 1, 1994, 1 Dec 1994 or 12/01/94 . 

Month names can be any size and case. 

Year can be short or long. There must at least two delimiters. 
Delimiters -- any combination of non-alphanumeric characters" 

| iteml item2 newMonth newYear array dels aString| 
aString := aDateString. 

dels := aDateString select: [:i | i isAlphaNumeric not], 
dels isEmpty ifTrue: [ A self error: 'Improper Date Format'], 
dels do: [:d | aString := aString copyReplacing: d withObject: 

$ ]. 

array := aString substrings. 

array size = 3 ifTrue: [ "Normal date pass it on to Date class 
method" 

A self setNewDate: (Date fromString: aDateString)]. 
iteml := array at: 1. 
newYear : : = (array at: 2) asNumber. 
newYear < 100 ifTrue: [newYear := newYear + 1900]. 

iteml first is Letter 

ifTrue: [ "Dec 94 format" newMonth := Date match: iteml] 
ifFa'se: [ "12/94 format" newMonth := Date nameOfMonth:( 
iteml asNumber)]. 

A self setNewDate: ( Date 
newDay: day 
month: newMonth 
year: newYear) 

This method is not very complex, and it does a good job of handling 
code reuse by calling an existing method. We wall now move on to the 
method that will use this method. 
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Creating a Prompter for the Date 

Now we need a menu method for class CalendarWindow to display a 
prompter, into which the user can enter a date to navigate to. It is a 
fairly straightforward method. Here’s its code: 

gotoMonthYear: aWidget clientData: data callData: moreData 
"Query user for a date or month-year string, then display 
new calendar based on user entry" 

| answer date | 
answer := CwTextPrompter new 

titie: 'Go to Date'; 

messagestring: 'Enter a Date or the Month and Year: 

answerString: 'July 1994'; 
prompt. 

answer isNil ifTrue:[ A self]. "user canceled" 
date := calendar setDateFromString: answer, 
date is Ni1 if F a 1s e: 

[self updateCalendar] 

Notice that the prompter will return nil if it is canceled. In that case, 
we simply return self and do nothing. 

This is a good time to save your application. Also, to be sure you don’t 
have any windows or other objects assigned to the global variables, you 
should set them to nil like this: 

Tigger := Scott := nil. 

Testing the Application 

We’re ready to begin our testing. Type the following line into the Tran¬ 
script or a Workspace and Execute it: 

Scott : = CalendarWindow new open. 

You immediately get an “Undefined Object does not understand date” 
error (See Figure 7-8). We put this bug into the program to provide a 
little more practice in the IBM Smalltalk debugging environment. The 
debugger is automatically opened for you. 
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Figure 7-8. 


The [Debugger window in the first test of CalendarApp 


When the Debugger opens, a message is highlighted. This is the mes¬ 
sage that caused the exception to occur (see Figure 7-9). Looking down 
the list, we can see the messages that sent this message. As you scan 
down the list, you should see some familiar method names, right up to 
updateCalendar (you may have to scroll down to see it). Click on 
updateCalendar. This method is calling date. In the center column of the 
Debugger is the list of variables used in this method. Notice the variable 
calendar is not present. The reason for this absence is that calendar is 
an instance variable, not a temporary variable. To see the instance vari¬ 
ables, we need to bring up an inspector window on the CalendarWindow 
instance. Do this by double-clicking on the word “self’ in the center list. 
Click on “calendar.” The current contents of the object are displayed in 
the column on the right. We can see that “calendar” is nil. 

What is going on here? We added this code after we did our smoke 
test, but it should not have created a problem like this. Look at the method 
below this one, which is addDatesRegion: . We must still be in the middle 
of opening the windows. Let’s verify that by looking further down the 
list. Yes, the next method down is open. Look at the open method. The 
method setUp isn’t called until later in the method. So the calendar in¬ 
stance variable isn’t assigned yet. Well, this looks easy, all we have to do 
is move the call to the setUp method to the top of the open method. Now 
close the debugger and let’s try testing again. 
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Figure 7-9. 


| The inspector window on the CalendarWindow instance 


.Scott := CalendarWindow new open 

Oh great, another debugger. Now what? What does it mean by “dayOf- 
Month not understood”? Open the Debugger and see where we are. Look 
down for a name we recognize. There’s one, highlightCalendar. It ap¬ 
pears we are highlighting a date. Let’s look at the center column and see 
what is there—self, today, and holidays. They are set to aCalendarWin- 
dow, nil, and an empty collection. So why is today nil? Let’s inspect the 
Calendar instance; maybe today is not a Date. We will need to bring up 
two inspectors; one on self, then within that inspector, one on “calen¬ 
dar”. No such luck; the today variable is a Date. So why would a Date 
not understand dayOfMonth ? 

Wait a minute. The error says that Calendar does not respond to 
monthDay. We just checked, and today is not a Calendar. Things con¬ 
tinue to get even more bizarre. Let’s look more closely at the process. 

The highlightCalendar: method is querying the Calendar instance for 
today’s date, then asking for the resulting Date object’s dayOfMonth. Yet 
the error references Calendar instances, not Date instances. Now you 
see the value of assignments to temporary values instead of long mes¬ 
sage sends. Let’s look at the method. Browse on Calendar>today. Do you 
see anything significant? We answer the result of the initialization method. 
What is the result of this method? We don’t return a specific value from 
this method, and we know the default return value is always self. That 
explains why the error is on Calendar instances; we are answering not a 
date, but self, which is a calendar. 
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Let’s not beat ourselves up too badly; at least this is easy to fix. Add a 
line to the today method that returns today and remove the caret from 
before self. Don’t forget the period at the end of the initialization line. 
(We leave it up to the reader to determine if that was an intentional 
bug.) Now we are ready for another smoke test. 

Scott := CalendarWindow new open. 

Success ai: last! Now is the time to test all the features. Execute the 
following lines: 

Calendar adcHolidayFromString: '12/25/94'. 

Calendar adoHolidayFromString: '2/2/95: 

Calendar addHolidayFromString: 'Jan 1, 1995'. 

Calendar addHoliday: Date today. 

Now navigate to different months, especially months with holidays. 
Notice anything strange (hint, hint)? 

First, the g;reen highlighting is not going away. All months seem to be 
highlighting today. Looks like another today bug. But wait, the holidays 
are also showing up in all the months, as is the day of the week. Our 
conditional testing in highlightCalendar must not be working. Let’s con¬ 
firm this by going back to today. Now click to the next month. This is 
interesting. Today’s date isn’t highlighted, just the location of today’s 
date. Click to next month to see how the highlight stays with the loca¬ 
tion, not the date. Also, the holidays appear to be doing the same. So, if 
it is the locations that are remaining highlighted, and not the dates them¬ 
selves, it isn’t likely that the problem is with our conditional testing. 

So what else could it be? If it is location related and not date related, 
then we should be able to prove this fact by setting a holiday on a date in 
a different month that is in the same location as today. Look one month 
ahead and set a holiday on the date that falls in the same location as 
today. In our case it is: 

Calendar addHolidayFromString: ''Oct 19,1994' 

Now navigate to months after this month. Notice how the location is 
now red in each month. Click back to today. The location is green. Now 
click to previous months; they are all green. So when the location is set 
to red, it stays red and when green, it stays green. In other words, the 
color is sticking to the location until changed. The problem is we are not 
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resetting the color to black, so it remains whatever color it is set to. 
What do we do about this? We need to turn all dates black before they are 
highlighted. The best time to do this is when we are assigning them labels. 
This would also be the time to reset the weekday labels’ colors as well. 

Add the following code to updateCalendar at the end of the loop and 
before the self setLabel message; be sure to first remove the extra bracket 
from the last line. 

aButton foregroundColor: CgRGBColor black]. 

Next add this line below the above line: 

weekdays chi 1drenDo: [:c | c foregroundColor : CgRGBColor black]. 

Close the Calendar window and retry the test with: 

CalendarWindow new open. 

Now when you navigate to one of holiday’s months, you’ll find that the 
proper date is highlighted in red, and when you leave the month the 
location is changed to black. Also, the green highlight appears only in 
today’s month. 
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This chapter describes how to create and manage IBM Smalltalk appli¬ 
cations that use more than one window. When a multi-window applica¬ 
tion involves interaction and communication between windows, we will 
use an event management approach that is different from the techniques 
described in Chapter 6. 

We will begin this discussion by describing why and how disparate 
objects that share an application space can communicate with one an¬ 
other using a technique called message broadcasting. Then we will ex¬ 
amine some of the deficiencies of this approach for certain needed kinds 
of communication between elements of an application. For these situa¬ 
tions, we will suggest an alternative approach we call moderation. 

Inter-Window Conunication 

Because the Calendar application we built in Chapter 7 required only 
one window, it communicated events to itself. All of the methods needed 
for handling events were defined in one class. All messaging was intra¬ 
window, with messages passing between components contained in the 
window. Any o ther communication took place between the window and 
extra-application objects such as the desktop. 

In Chapter 9, we’ll be adding another feature to our growing 
SimplePIM application, one that requires the creation and management 
of a second window and the synchronization of the two windows’ con¬ 
tent and behavior. When we need to support multiple windows, we need 
a messaging system that extends beyond intra-window communications. 
Such a system would, among other things, handle notification of one 
window that something has changed in another window. 
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Fortunately, we don’t need to learn a whole new messaging system 
for this because we’ve actually only scratched the surface of IBM 
Smalltalk’s built-in messaging architecture. 

What Windows Have to Say 

There are three fundamental reasons windows need to communicate 
with other windows in the same application and with other applications: 


m To notify one another of pending events 
m To pass data back and forth 

m To synchronize operations like activation and closing 


Event Notification 

The calendar we built in Chapter 7 will be far more useful to its users if 
it is able to communicate the date the user has selected to other win¬ 
dows and applications. In an era when component software is emerging 
as an important concept, this ability to “stay in touch” with other objects 
in the user’s environment is quickly becoming an expectation. 


Data Transfer 

As a matter of sound object-oriented design, it is not a good idea for any 
object to be required to keep track of information about another object. 
Encapsulation mandates that information be maintained by the object 
to which it belongs. To the extent that an object is designed to share data 
with other objects, the sharing object should provide accessor methods 
through which the data can be retrieved and (optionally) modified. 

If we define a technique by which information maintained by a win¬ 
dow can be sent to other windows and objects interested in its state, we 
can enforce encapsulation without crippling the application or encum¬ 
bering it unnecessarily with a web of hard-wired links. 

Synchronizing Operations 

It is often useful in an application to connect two or more windows in 
such a way that, while all are independent of one another, there is a 
linkage that makes their use easier. For example, it may not make sense 
for an appointment book window to stay open if the calendar with which 
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the user navigates around his or her schedule is closed. So we may wish 
to synchronize the opening, closing, and minimizing of windows so that 
they all maintain an identical (or at least logically compatible) state. 

Broadcast iig Messages 

Any intercommunication such as we have been describing will inevita¬ 
bly involve objects sending messages to one another, since we know that’s 
the only way anything happens in Smalltalk. 

As long as we are dealing with only two windows that need to stay in 
touch with one another, we can use the standard event management 
techniques described in Chapter 4 and demonstrated in Chapter 5. But 
as soon as we add objects, the disadvantages of this approach become 
immediately apparent. If Window A needs to notify Windows B, C, and D 
that something about its content has changed, it will have to generate 
the same message information three times, create a repeating block struc¬ 
ture of some sort, or create an array of receiver objects and traverse it. 
Now when you want to add Window E to the list, you’ll have to modify 
the code to make Window A aware of the existence of Window E. Not 
only is this inefficient, it’s messy. 

Fortunately, Smalltalk provides a strategy for avoiding this mess in 
the form of broadcast messages. 

Depending on One Another 

The heart of the concept of broadcasting messages in IBM Smalltalk is in 
the notion of dependency. The basic rule is that any object can broadcast 
messages to its dependents. Each object can maintain a dynamic set of 
dependents, with each dependent responsible for registering its desire 
to be notified of messages or to be bypassed. Because all of the messages 
that create, destroy, and manage dependency relationships are defined 
in class Object, the dependency mechanism is universally available in 
IBM Smalltalk. 

To make itself a dependent of another object, an object sends the de¬ 
sired object the message addDependent:, with itself as an argument. 
Presuming the existence of a window called MyMainWindow, then, a 
second window could notify MyMainWindow of its desire to receive broad¬ 
cast messages by including the following line in its definition: 


MyMainWindow addDependent: self. 
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To remove itself from the list of dependents of an object, the depen¬ 
dent object sends its host the removeDependent: message, again with 
itself as an argument, as in this example, which undoes the effect of the 
preceding example: 

MyMainWindow removeDependent: self. 

These messages are the only ones the dependent object needs to worry 
about to establish and cancel the relationship. Obviously, the dependent 
object will also have to define a method to react to any messages the 
host object might broadcast and to which it wishes to have a response. 

The host object, on the other hand, has four messages available to 
help it play its role in the broadcasting mechanism: 

m The dependents message returns an ordered collection of all objects 
that have registered as dependents of the object. 
m The release message deletes all references to all objects, ridding the 
object of all dependents. 

■ The broadcast: message takes a method symbol (a message selector 
preceded by a pound sign) as an argument. 
m The broadcast:with: message takes a keyword method symbol and 
an object to pass as an argument. 

The purpose of the first two messages is self-explanatory. The last 
two messages are used actually to send a message to the object’s depen¬ 
dents. They are addressed to the dependents (which, as you can see, 
make up an ordered collection), as in this example: 

dependents broadcast: #closing. 

This line would send a notice to all of the current object’s dependents to 
let them know that the message closing is about to be executed. Each de¬ 
pendent can then take any appropriate action (including, possibly, broad¬ 
casting the information to other objects that are in turn dependent on it). 

Too Much Dependence 

At first glance, you might wonder why we would be about to discuss 
some other mechanism for handling interdependence of objects in a multi- 
windowed application. After all, it seems like we can send anything, in¬ 
cluding particular events, through this broadcast mechanism using de- 
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pendencies. So why would we introduce some other approach? Isn’t 
enough enough? 

There is one serious potential drawback to the overuse of the broad¬ 
cast mechanism: It couples objects much too tightly to one another. For 
an object to assign itself as a dependent, it must have access to the ob¬ 
ject it wishes to play the role of host. But a fundamental idea of object- 
oriented programming—encapsulation—argues against such knowledge. 
The more one object needs to know about another, the more tightly the 
two objects are said to be coupled. Tight coupling in an OOP design is 
considered a weakness because it reduces the modularity and reusabil¬ 
ity of individual objects and pieces of code. 

Besides the philosophical design problem (which we don’t wish to mini¬ 
mize, but which is often seen as a less than compelling argument), there is 
a practical issue: The more time a window has to spend tracking other 
objects, the less time it spends performing the real function for which it was 
created in the first place. Performance overhead can become a major im¬ 
pediment to the successful deployment and use of the application. 


We have seem a iiiumber of designs in Smalltalk where the misuse of the depen¬ 
dency and broadcast techniques has created an unnecessarily slow application, for 
which Smalltalk then takes the rap. You can design slow Smalltalk programs, but 
you can also design and build quite efficient applications in Smalltalk. As with all 
other programming languages, optimization is a skill that comes with experience. 




One effective way of dealing with this problem of overdependence on a 
mechanism that couples objects together too tightly is to create a kind of 
moderator object, the role of which will be to handle all interactions 
among objects in an application or subapplication. We’ll create such a 
class in Chapter 9 when we add a window to our growing SimplePIM 
application. 

This neutral object will act much like the coordinator of a mythical 
convention of superheroes: It will quietly and unobtrusively handle 
everyone’s business with everyone else without revealing anyone’s identity. 
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The responsibilities of this ApplicationController class will include: 


a Keeping a list of open windows and applications 
m Maintaining aliases for windows to protect their anonymity 
m Connecting windows and applications to the dependency network 
m Forwarding requests from one object to another 
m Synchronizing events among windows and applications 


To maintain anonymity, each object will publish a list of the messages 
and events it understands as well as an alias by which it can be refer¬ 
enced. As long as this class is going to handle all of that interaction, we 
may as well also assign it the responsibility of launching each applica¬ 
tion and its windows. 




CHAPTER 


The Fourth Project: 
An Appointment Book 


In this chapter we’ll use the multiple-window framework discussed in 
Chapter 8 to extend the Calendar application we built in Chapter 7. We’ll 
add an interactive appointment book capability to the calendar project, 
enabling it to keep track of appointments in a separate window. 

As usual, we will begin by describing the functionality we want from 
our new project. Then we will focus on the key design issues that arise 
in this context: displaying multiple windows in a single application and 
managing the synchronization of events among those windows. Along 
the way we will create an ApplicationController class whose job will be 
to manage our applications as well as launch them. We will integrate the 
existing Calendar application into this new framework. 

Specifying the Application 

The Appointment Book integrates with the Calendar application, but the 
book itself will appear in a separate window. It will be labeled with the 
weekday, month, day, and year whose appointments are being displayed. 
It will consist of a list widget, a text widget, and several label widgets. 
This window will also include an Edit menu to support manipulation of the 
appointments, which will be displayed as free-form text in the text widget. 

The date whose appointments are shown in the new window will be 
determined by the user manipulating the Calendar application’s win¬ 
dow, which will always be available when the Appointment Book is dis¬ 
played. The user can perform four operations: 


m Click with the left mouse button on a date in the Calendar window. 
m Click on the Today button. 

m Select a navigation option from the Calendar menu, 
a Choose a menu option from the Appointment Book’s own menu. 
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Other buttons and menu selections in the Calendar application will 
not affect the Appointment Book’s display. 

Days on which one or more appointments are scheduled will be dis¬ 
played in dark blue. The selected day will also be highlighted. If the user 
selects a holiday from the Calendar, a label widget in the Appointment 
Book window will display the description of that holiday. 

The Appointment Book will also support cutting, copying, and pasting 
appointments. The user can select an appointment, cut or copy it, move 
to a new date in the Calendar, and paste the appointment. The selected 
day schedule will be displayed, allowing the user to choose individual 
appointments. Appointments will consist of a start time, an end time, 
and a description. 

An appointment will be saved when the date is changed by the user, 
when another appointment is selected, when the application is closed, 
or when the user explicitly requests that it be saved by using a menu 
selection. An appointment can be deleted as well. 

In addition to the menu for the Calendar, we will add two new menus 
to the Appointment Book. These menus will be called Edit and Appoint¬ 
ments. In a traditional, procedural environment, the programming staff 
would moan and groan over these kinds of changes! But you’ll see that 
Smalltalk was built to accommodate these kinds of enhancements and 
extensions to applications. You’ll be pleasantly surprised at how easy 
most of these changes are. 



A frequent criticism of Smalltalk as a development language centered 
on its tradition of using multi-paned windows for applications typically 
displaying a single window at a time. “I can tell a Smalltalk application 
just by looking at it,” was a common boast among people who saw pro¬ 
grams written with early versions of Smalltalk. 

This criticism is no longer valid in light of IBM Smalltalk and the emer¬ 
gence of strongly windowed host GUIs like Windows. As we saw in Chap¬ 
ter 8, IBM Smalltalk provides a great deal of support for the multi-win- 
dowed applications, which users increasingly expect and even demand. 

From what we know about the Calendar application, and what our 
AppointmentBook extension needs to do in conjunction with that appli¬ 
cation, we can define a number of dependencies between the two win¬ 
dows in our growing program. 
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We must modify the CalendarApp window and its related code to notify 
the AppointmentBook window when any of the following events occur: 


m The user selects a new date. 
m The user adds a holiday to the calendar. 
m The currently selected date is a holiday. 
m The Calendar window is activated. 
m The Calendar window is closed. 

Similarly, CalendarApp needs to be aware of the following activities 
and events associated with the AppointmentBook window: 


h The user adds a new appointment (so Calendar can highlight the 
day). 

m The AppointmentBook window is activated. 
m The AppointmentBook window is closed. 


In addition, the Calendar needs to be able to extract from the 
AppointmentBook all the appointments for a given month so that it can 
highlight them in its month view. 

By concentrating synchronization and data update processes in the 
new ApplicationController class, we can avoid the necessity for the in¬ 
dividual objects to know about one another. Our ApplicationController 
will dispatch events and information for both window objects. 

Setting lip the Project 

You can choose from several options for working along with this chapter 
on your own system. Each option requires you to load a specific applica¬ 
tion file from the accompanying disk. 

If you want to type in all the code yourself, just file in the 
SMPLEPM.APP application file from the Chapter 7 directory, which will 
start you where we left off. 

To load a complete working version of the project in this chapter and 
follow along without typing any code yourself, file in the SMPLEPIM.APP 
application file from the Chapter 9 directory. 

The examples that are not part of the project but that are included in 
line in the text of this chapter are stored in the file CHAPTER9. WSP in 
the Chap09 folder as well. If you don’t want to type the examples, just 
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open a Workspace on this file. Then yon can select code as we discuss it 
in the book and execute it. 

Regardless of what you decide, you will need to set the default applica¬ 
tion to the SiixiplePIM Application (a process you learned in Chapter 7). 

There are a couple of final things to note: Remember when saving an 
application file to name it something different from the supplied files. 
Also, you should note that you cannot load a SimplePIM application if 
the application has already been loaded (that is, if your image contains 
this application from Chapter 7). You must first delete the application, 
then load the file. 

Gaining Some Experience with Time 

In Chapter 7 we were concerned with Date, but in this chapter Time will 
be the focus. Appointments are time related. They have a beginning time 
and an end time. Let’s take a moment to look at the Time class, since we 
will more than likely need this knowledge later in the chapter. 

Open a classes browser and find the class Time. Let’s begin our explora¬ 
tion with the class methods. The first question, as it is with all objects, is 
how to create a Time object. Try these examples by inspecting each of them: 

Time dateAndTimeNow 
Time fromSeconds: 30000 
Time now 

An informative method is: 

Time secondsPerDay. 

As you would expect, there are instance methods for hours, minutes 
and seconds. Try the following: 

Time now hours 
Time now minutes 
Time now seconds. 

This instance method allows you to change the elements of a Time 
instance. Inspect it to see the results: 


Time now hours: 18 minutes: 10 seconds: 20 
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We used the class method now to get a time instance to work with. It 
seems strange that there is not an equivalent class method. Except for 
some format methods and time addition and subtraction, that’s all for this 
class. We should have enough data to create our first class, Appointment. 

Defiiiiif the Appointment Class 

The first class we will tackle will be the Appointment class. This class 
will hold the elements of an individual appointment, namely its start 
time, end time, and text description. The class will provide support for 
three key actions: displaying each element as a string, parsing those 
strings into time objects, and comparing times. The class will also pro¬ 
vide a scheme for comparing times. In addition, it will provide a class 
method for easy creation and instantiation of appointment objects. 

The Appointment class will be an Object subclass and will define three 
instance variables: start, end, and entry. The class definition follows: 

Object subclass: #Appointment 

instanceVariableNames: 'start end entry ' 
classVariableNames: ' ' 
poolDictionaries : ' ' 

With the class definition out of the way, we can define the class method. 
This method is quite a bit different from the standard new method we 
normally create. It is named start:end:entry-., and it not only creates an 
appointment, it sets its contents as well. Here is the class method: 

start: startTime end: endTime entry: aString 
"create a new appointment with startTime, endTime and a blank entry" 

I I 

A super new start: startTime end: endTime entry: aString. 

This single class method replaces the several message sends that are 
normally required to create an object and then load its instance vari¬ 
ables. It just makes using an appointment more convenient. The actual 
work is performed by an instance method identically named 
start:end:entry:, as shown here: 

start: startTimeString end: endTimeString entry: aString 
"set start, end and entry " 

start: := self modifyTime: (self parseTimeString: 
sta rtTimeString). 
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end := self modifyTime: (self parseTimeString : endTimeString). 
entry : = aString. 

This method calls, in turn, two other instance methods. We’ll take a look 
at modifyTime: and save the other method for later. The modifyTime: method 
takes a Time object and sets its seconds to zero. Here is the method: 

modifyTime: aTime 

"answer a time with seconds zeroed " 

| newTime | 
newTime := aTime. 

A newTime hours: aTime hours minutes: aTime minutes seconds:00 

Why do we want a zeroed time? For two reasons: The first reason is 
that we can assume that user entries will not include seconds. The sec¬ 
ond reason has to do with comparing two times. By setting the seconds 
to zero, we have a comparison based on minutes. Since appointments 
are normally set on the hour, half hour, and quarter hour, using a minute 
base makes sense. Seconds would only complicate things, making 8:30:01 
and 8:30:05 different times. This approach will become clearer as we 
continue with this section. 

Passing the Time 

The next method performs a more complex task. It must parse a string 
for a time. We can imagine that time might be entered in the following 
formats: “08:30 AM,” “2 PM,” and the very lazy “8” with the “AM” as¬ 
sumed. We have already had some experience with parsing dates, and 
times should not be much harder. Let’s take it a step at a time. First, like 
the date, we need to divide the time based on a character. Let’s use a 
colon ($:). So the first few lines of the method would look like this: 

parseTimeString: aString 

"answer a time created from aString in the h:m am/pm format" 

| time hour minutes pm| 
time : = aString asUppercase substrings: $:. 

Just as with a date, we store the string into an array of substrings. We 
also remove any problems with case by converting the whole string to 
uppercase. Next, we need to work with the substrings to find the appro¬ 
priate time parts. We can assume that the first array element will con- 
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tain the hour and that the second array will contain the minute and the 
AM/PM of the present. Here is the next piece of code: 

hour :=( time at: 1) asNumber. 

time := time at: 2. 

pm := ( time at: (time size - 1)) = $P. 

pm ifTrue: [ hour := hour + 12]. 

We check for a PM, and only if we find it do we set the hours to 24-hour 
time. This means times without AM/PM will work and will be set to AM. So 
“8:30” becomes 8:30 AM (actually 08:30 in 24-hour time). But what about 
“2 pm”? Without the $: character, this code will fail, since it expects two 
elements in the array, and only one would exist. Apparently our assumption 
above wasn’t very accurate. We need a way to check the size of the array. 
Aha! The size method, of course. Let’s think this through a little. Two 
substrings mean that the $: character is present and that the second substring 
holds the minutes. One substring means that the $: is missing and that 
minutes are zero. With this in mind, we can proceed with a modified ver¬ 
sion of the last section of code. Changes are boldfaced: 

hour :=( time at: 1) asNumber. 

time size = 2 

ifTrue: [ time := time at: 2. 

minutes := time asNumber] 
ifFa 1 se: [time := time at: 1. 

minutes := 0]. 

pm := ( time at: (time size - 1)) = $P. 

pm ifTrue: [ hour := hour + 12]. 

Let’s finish up the method by creating a time instance with some code 
we found during our exploration: 

A Time now hours: hour minutes: minutes seconds: 00. 

Look familiar? Watch out for these pop quizzes. I suppose now you 
want to test this code and see if it works. We can easily do that since we 
have already written the methods that use this method. Try: 


Appointment start: '8:30 ' end: '10:30' entry: 
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A Debugging Trick 

One thing you may like to do before you test the code is to make the 
result a little more informative than “anAppointment.” Here is a debug¬ 
ging trick: Create a method called printOn: that will override the Object 
method. Here is the method we use: 

printOn: aStream 

"display object information" 

aStream nextPutAll: '@, start printStringentry. 

This code will display “@8:30 A:” for the above example. If you want 
to see the default anAppointment instead of just add this line before 
the last line: 

aStream nextPutAll: ( super printOn: aStream). 

We prefer output without the line since it makes the display smaller 
and easier to see in displays of collections. You can put any data from 
your object into the method. The resulting display is seen in inspectors 
as well through the “Display” menu option. 

Some More Testing 

With the debugging code entered, you can try all the formats we sug¬ 
gested earlier, such as “8 PM,” “8 AM,” “10,” and “8.” If you try the lazy 
man’s “8” you will get a primitive error. It seems strange that “10” works, 
but not “8.” Actually the reason is quite clear. Trying to back up one 
character by subtraction on a single-character string in our 
ParseTimeString method leads to a bad index value. Another assump¬ 
tion gone astray. So what to do? 

You can check this for yourself by trying “8 ,” with the space after¬ 
wards, and seeing that this does work. Well, it seems obvious we need 
another conditional check, which may be one of the reasons why people 
who write complex parsers are paid very well. 

Let’s succumb to our design decision and resolve this one last prob¬ 
lem. We need to make sure that the index we are using is never negative 
and is not more than the size of the substring. We need some code simi¬ 
lar to the code we used to fix the last problem, but based on the resulting 
time variable size. Here is the complete method — changes are in bold, 
and testing is left to you: 
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pa rseTi me St ri rig : a St ring 

"answer a time created from aString in the h:m am/pm format" 

| time hour' minutes pm size | 
time := aString asllppercase substrings: $:. 
hour : = ( time at: 1) as Number, 
time size = 2 

ifTrue: [ time := time at: 2. 

minutes := time asNumber] 
if False: [time := time at: 1. 
minutes := 0] . 
size := time size > 1 
ifTrue: [time size - 1] 
if False: [time size], 
pm := ( time at: size) = $P. 
pm ifTrue: [ hour := hour + 12]. 

A Time now hours: hour minutes: minutes seconds: 00. 

The Display Methods 

With the parsing method complete, we can move on to the display meth¬ 
ods. These methods will format the Appointment elements into strings, 
which are preferable for display in the Appointment Book. 

The first method is a generic method that converts a time into a string, 
the opposite action from that of the parsing method above. The method 
is called displayTimeString: and, as you may have guessed, it takes a 
time object as an argument. Here is the entire method: 

displayTimeString: aTime 

"answer a string with aTime in hh:mm am/pm format" 

|hours minutes string | 
string : = 'AM'. 
hours := aTime hours, 
hours > 12 

ifTrue: [ hours := hours - 12. string : = 'PM'], 
hours := hours printStringRadix: 10 padTo: 2. 
minutes := aTime minutes printStringRadix: 10 padTo: 2. 

A hours minutes,' '.string. 

This method is pretty straightforward, with only a couple of little tricks 
that might bear some explanation. Notice that we set the string string to 
the default state and change it only if it is warranted. The printstring- 
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Radix.padTo: method is a convenient utility for padding an integer with 
a left-aligned zero fill. 

The next two methods use the previous method and are quite simple 
as a result. Here they both are: 

displayStartTime 

"answer start in display format" 

A self displayTimeString: start. 

displayEndTime 

"answer start in display format" 

A self displayTimeString: end. 

Finally, we need the method that displays the entry. Since that entry is 
already a string, we simply answer the variable. This set method is left 
to you, along with get. 

A Utility Method 

We’ll finish up this section with a public method designed to make it 
easy to compare a user-entered time string to an appointment start time. 
This method will be useful for selecting appointments out of a collection. 
Here is the method made simple by using one of our already defined 
methods (it’s so easy when you have the right tools): 

matchStart: aString 

"answer if aTime = start" 

A start = (self parseTimeString: aString). 


Creating the AppointmentBook Class 

With design issues and the Appointment class out of the way for the 
moment, we can begin coding our application. We’ll begin, as usual, by 
defining a new Object subclass, AppointmentBook. Its class definition 
looks like this: 
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Object subclass: #AppointmentBook 

instanceVariableNames: 'appointments currentDate currentAppt 
schedule ' 

classVariableNames: 'Appointments' 
poolDict'onaries: ' ' 

Notice that we intend to track currentDate , currentAppt , and sched¬ 
ule in addition to appointments. We’ll cover each of these variables in 
more detail as we use them. 

One question that arises is where to keep track of the appointments 
the user creates. One possibility is to store them in a class instance vari¬ 
able as we did with Holidays . This worked well, so we’ll continue the 
trend with Appointments. As a class method, we can always access and 
use them later with future enhancements to our product. 


The reason we did molt use a global variable is that gSobals require you to save the 
image after setting them. If this is not done, then they must be reset each time you 
start BBIVS Smalltalk. If the global is undefined in the image, any code that uses the 
global will not compile and will report errors in the Transcript, including code 
loaded in from external fifes. In our experience, it is the external code problem that 
Is the most difficult to get around, which prompted us to use a class variable. 



Hie Initialization Method 

The first method we’ll define is initialize. By now you realize that this is 
usually the fi rst thing we do so we can create and test new instances of 
our object as early in the development cycle as possible. Here’s the code 
for this method: 

initialize 

"make sure appointment book is pointing 

at stored appointments" 

appointments := self class appointments. 

We hold appointments in the class variable Appointments. This per¬ 
mits us to save appointments between sessions. By using the instance 
variable appointments rather than directly accessing the class variable, 
we combine changes to the class or structure of the Appointments class 




variable to this method. Also, using the class method rather than di¬ 
rectly accessing the class variable helps encapsulate the data. 


The Instance Creation Method 

While we’re working on initialization, let’s define the new class method 
for AppointmeetBook: 

new 

"Create a new appointment book" 

A super new initialize. 

Nothing surprising here. It looks like all the other new methods we’ve 
created. 

Making Appointments Easy to Access 

We don’t want other classes to access the Appointments variable di¬ 
rectly, so let’s give them a way to access it through our class. This way, if 
we decide to change our storage mechanism, such as moving it to file, 
we won’t have to find and change every reference to our class variable. 
We’ll also use automatic instantiation as we did in Calendar. Here is the 
class method to handle this task: 

appointments 

"Answer Appointments after making sure it is initialized" 
Appointments is Nil ifTrue: [ Appointments := Dictionary new]. 
A Appointments 


The Content-Retrieving Method 

We need a method that will retrieve the schedule so that access to its 
contents will be object-oriented and well managed. Here is the instance 
method that will handle this assignment for us: 

scheduleFor: aDate 

"answer the collection of appts for the current day" 
currentDate := aDate. 

A self getCurrentDaySchedule 
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We assign the date passed with the message to the instance variable 
currentDate . Then we use the getCurrentD ay Schedule method (which 
we’ll write shortly) to retrieve the string representing the appointments 
for the day in question. Later, we’ll use this method in an upDate method 
in AppointmentBookWindow to display the current schedule. 

Schedule-Related Methods 

Our design calls for AppointmentBook to display the schedule for the 
currently selected day in the Calendar. Here is the code that accom¬ 
plishes this task: 

getCurrentDaySchedule 

"Private - answer the appts for the currentDate or an empty 
col 1ection" 

I appts | 

schedule := self appointmentsAt: currentDate. 

schedule isNil ifTrue: [ schedule := self newSchedule]. 

A schedule collect: [:a | a displayStartTime]. 

This method is called by the scheduleFor: method described in the 
previous section. It uses the value of the instance variable currentDate , 
set in the method scheduleFor to locate the collection of appointments 
for that day in the Dictionary of appointments. It assigns this collection 
to the instance variable schedule. If the collection is empty (in other 
words, there are currently no appointments for the date), this method 
creates a new collection using yet-to-be-defined newSchedule. Using this 
method instead of directly creating a collection allows us to change the 
kind of collection later if we like, by modifying one method. Finally, the 
method uses the Collection method collect to create a collection of strings 
produced by the Appointment method we defined for that purpose. Nice 
to know you are creating practical methods, isn’t it? 

We’ll store data for the appointment in an instance of a Smalltalk 
Dictionary object, and we’ll store the descriptions as strings. The date 
will act as the key in a Dictionary created for this purpose, and the 
appointments will be stored in a SortedCollection. A SortedCollection is 
used to ensure that the times are displayed in ascending time order, the 
way most “paper” appointment books display them. 

Let’s catch up on some of the methods we created a need for earlier. 
The first of these was appointmentsAt: , a method defined in order to 
control access to the Appointments variable. Its one line of code is: 
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appointmentsAt: aDate 

"answer the appoinments on aDate or an empty collection" 
A appointments at: aDate ifAbsent: [ A ni1 ]. 

The only thing to note here is that if a date is not found, a nil is re¬ 
turned. We took advantage of this in the last method in order to answer 
an empty collection for non-appointment days. This scheme keeps us 
from having empty collections on dates the user selected but for which 
no appointments were entered. This is an advantage because it reduces 
the memory space used by the application. 

The next method is the method we provided to encapsulate the cre¬ 
ation of a new schedule collection. It is called, appropriately enough, 
newSchedule and is coded thus: 

newSchedule 

"answer an empty schedule collection" 

A SortedCol1ection new. 


Sorting Appointments 

The knowledge that appointments are stored in a SortedCollection cre¬ 
ates the need to reexamine how we intend to sort appointments. 
SortedCollection sorts based on a two-argument sort block. The sort 
block defaults to: 

[:a :b | a <= b]. 

Obviously, this technique will not work for an appointment, since it 
does not support the <= operator and is a complex object. What we need 
to do is set an appropriate sortBlock each time a new SortedCollection 
instance is created, or else we must loverride the operator method. Let’s 
live dangerously and do the latter, since the former requires changing 
existing code, some with the paint barely dry. 

We need to switch back to the Appointment class and prepare to enter a 
new instance method. To override the method, we need to decide what 
we want to sort on. How about the start time of the appointment? We just 
need to create a method that compares appointment start times. Maybe 
this approach isn’t so dangerous after all. The code is revealed as: 
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<= anAppointment 

"determine if a Time is less than receiver" 

A self start <= anAppointment start 

The operator method is created the same as any other method. In it, 
we compare self to a past appointment. With the addition of this opera¬ 
tor, we won’t have to worry about sort blocks. We do need a start , and 
while we’re at it, an end method. Here are two accessor methods: 

start 

"answer my start time" 

A sta rt 


end 

"answer my end time" 

A end 

Now we can return to AppointmentBook confident that collections 
will have no additional problems with appointments. 

Getting Appointments for a Given Date 

Remember that we need a method by which the application can deter¬ 
mine the appointments for a given month. We can easily handle this 
problem with a method that simply provides all of the keys in the Ap¬ 
pointments class dictionary, which, you’ll recall, we’ve stored in the in¬ 
stance variable appointments. The keys will then be used to find only 
the dates with appointments for the given month and year. Here is the 
code to handle this assignment: 

appointmentsInMonth: aDate 

"answer the appts for the currentDate or an empty collection" 

I appts | 

appts := OrderedCol1ection new. 
appointments keysDo: [:a | 

a monthName = aDate monthName 
ifTrue: [ 

a year = aDate year 

ifTrue: [appts addLast: a]]]. 


appts . 
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Since we store the appointments in an instance variable, which in 
turn contains a Dictionary, we can use the keysDo: method of the Dictio¬ 
nary class to return a list of all the current appointments. Then it’s sim¬ 
ply a matter of adding to the temporary appts collection those dates 
(keys) that pass our criteria check. If no days in the month have appoint¬ 
ments, an empty Collection will result. 

The Save Method 

Finally, we’ll provide a method the user can use to save an appointment 
entry. Here is the code: 

saveEntry: aString 

"save the currentAppt entry" 
currentAppt notNil 

ifTrue: [currentAppt entry: aString]. 

Entering an Appointment 

Before we can save an appointment, we need to be able to create and set 
one. We already created an Appointment class method to aid in this 
effort, so let’s use it to create a public method that can be called when 
the application needs a new appointment. Not only will the method make 
the new appointments and store them, but it will also answer the re¬ 
vised list of appointments. Here is this amazing method: 

start: startTime end: endTime entry: aString 

"create a new appt with startTime, endTime and aString 
answer revised collection" 

| appt appts | 

appt : = Appointment start: startTime end: endTime entry: aString. 
appts := self appointmentsAt: currentDate. 
appts isNil ifTrue: [appts := appointments at: currentDate 
put: self newSchedule]. 
appts add: appt. 

A self getCurrentDaySchedul e 

There shouldn’t be anything surprising here. All the methods called 
have been used elsewhere. 
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Generating a Label String for the Appointment 
Window 

Since we need to place the name of the day as well as the month, date, 
and year in the label of the Appointment Book window, we need a method 
in AppointmentBook to generate this string. Then we can use this method 
to display the appointments in a window with this string as a label. Here 
is the code for the method: 

weekdayMonthDayYearString 

"answer a string composed of currentDate elements" 
A currentDate dayName,' currentDate monthName,' ', 
currentDate dayOfMonth printString,', ' ,currentDate year 
printString. 

This method simply returns the string we want to use for a label. Its 
format will be something like “Friday January 1, 1995.” The string is a 
concatenation of the various parts of a date and can be easily custom¬ 
ized to your own liking. The date is based on the currentDate , so we 
need to make sure this date is set correctly as the user navigates through 
the Calendar. 

Some Utility Methods 

We know we need to delete appointments as well as create them and 
that the currentAppt will need to be set when a different appointment is 
chosen in the same day. Based loosely on the start:end:entry: appoint¬ 
ment creation method, here is the deleteAppointment method: 

del eteAppoi ntrnent 

"remove currentAppt from my appointments " 

currentAppt notNil ifTrue: [schedule remove: currentAppt]. 

A self getCurrentDaySchedule. 

You may have been wondering which method sets the currentAppt vari¬ 
able. It is the method we will call appointmentStarting: This method uses 
the Collection detect method and Appointment matchStart: method to find 
the appointment in the current schedule with a start time equal to the given 
time. The method answers the resulting appointment. The code follows: 



198 


IBM SMALLTALK 


appointmentstarting: aTImeStri'ng 

"Answer an appt with starting time aTIme or nil" 

currentAppt := nil. 
schedule not Nil 

IfTrue: [currentAppt := schedule detect: [:a | 

a matchStart: aTImeStri'ng] IfNone: []]. 

A currentAppt 

Finally, three methods are needed that solely use the Appointment dis¬ 
play methods to show the start time, end time, and entry of the currentAppt. 

sta rtT1 me 

"Answer end time of currentAppt as string" 

A currentAppt displayStartTime 

endTIme 

"Answer end time of currentAppt" 

A currentAppt displayEndTIme 

entry 

"answer currentAppt entry" 

A currentAppt entry. 


Changing the Calendar Class 

We will need to make some simple modifications to the class Calendar to 
accommodate the changes we are making. 

In our design discussion we determined that we want to store a de¬ 
scription as well as a date. We will store holidays in a Dictionary with 
the date as a key and the date’s description as the value. Now we need to 
modify newHolidays to create a new Dictionary instead of a Set. Here is 
the new code: 

newHolidays 

"create a new class holiday Dictionary" 

A Hol1 days := Dictionary new. 

This change has a ripple effect on four other methods. We’ll look first 
at the showHolidays method, since we programmed it originally assum¬ 
ing a Set and used the do: method to iterate over the Set. Here is the 
changed showHolidays method: 
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showHolidays 

"Answer a collection of holidays that fall in the current month" 

| aCollection | 

aCollection := OrderedCol1ection new. 

self makeNewDate. "Sync current date with other variables" 
self class holidays keysDo: 

[:each | ( each monthlndex = month ) ifTrue: 

[ aCollection add: each ] 

i 

A aCol1ection 

The only change from the old version in Chapter 7 is in the third execut¬ 
able line, where we substitute keysDo: for the do: method so we look only at 
dates that have a corresponding key in the Dictionary of holidays. 

We need two class methods to support the user’s adding holidays to 
the calendar: addHoliday: and addHolidayFromString: . Here’s the code 
for addHoliday: that supports a description for the holiday: 

addHoliday: abate named: aString 

"add a a Date and aString description 

to the Holidays Collection. Assumes a Date " 

| newDate | 
newDate := aDate. 

newDate := self modifyDate: newDate. 

A (self holidays) at: newDate put: aString. 

This method takes two arguments. The first is a date, and the second 
is a string desc ribing the holiday. Note that we use the modifyDate: method 
to convert it to our new format using a year of 0000, which we are using 
as an arbitrary base year for reasons we’ll explain shortly. The equiva¬ 
lent method that deals with a date entered as a string is as follows: 

addHolidayFromString: aDateString named: aString 
"add a aDateString and description aString 
to the Holidays Collection. Uses Date fromString: format" 

| newDate j 

newDate := Date fromString: aDateString. 
newDate := self modifyDate: newDate. 

A (self holidays) at: newDate put: aString. 
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The changes to this method from the old addHolidayFromString: 
method are equivalent to those in the addHoliday : method in the previ¬ 
ous paragraphs. 

Delete the old methods now, since they are no longer used and may 
confuse you or another programmer looking at this application later. 

Now that we have an appointment book window that looks at an indi¬ 
vidual date and needs to know if it’s a holiday, we need an efficient way 
of searching for holidays, regardless of the year. One way to do this is to 
give all holidays a base year, arbitrarily, of 0000. This will permit us to 
create a new method, isHoliday , to search through the holiday list and 
determine if the currently selected date is a holiday. This will take a few 
methods. (Of course, not all holidays occur on the same date each year. 
Holidays that don’t will require a different mechanism. We leave this 
problem as a challenge to the reader.) 

First, we have to have a class method that will accept a date as input 
and change its year to 0000. Here’s the code for just such a method, 
which we’ve called modifyDate:. Remember that it’s a class method and 
that we are still working in the class Calendar: 

modifyDate: aDate 

"Answer a modifed date with a year of 0000 
derived from aDate" 

| month day | 

month tm aDate monthName. 
day : = aDate dayOfMonth. 

A Date newDay: day month: month year: 0000. 

This method uses code from the instance method makeNewDate and 
supplies an arbitrary value of 0000 as the year. 

Having this method available, we can create an instance method that 
will convert a date to the new holiday format and return its description 
if the date is a holiday. We’ll have it return a new string if the date is not 
a holiday. Here’s the code: 

holidayDescription: aDate 

"Answers a holiday's description 
or empty string" 

| newDate | 

"convert to holiday format" 

newDate := self class modifyDate: aDate. 

A self class holidays at: newDate ifAbsent: [ A String new]. 
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Type the foSlowiny line into a file editor or the Transcript and Execute it: 

Calendar newHolidays 

Otherwise, showHolidays will fail during testing because the old Holidays variable, a 
set, will still be hanging around. The above line ensures that we are working with a 
Dictionary object 



Dealing with the User’s Date Selections 

In Chapter 7 we built the basic Calendar application using a rowColumn 
widget and a collection of label widgets for the calendar display. While 
label widgets do not respond to XmNActivateCallBack, their counter¬ 
parts, button widgets, do. Most widgets respond to events. There is a 
button press event that indicates a mouse button has been pressed. Per¬ 
haps label widgets will respond. Let’s explore. 

The first thing we need to do is update the CalendarWindow defini¬ 
tion to support some new instance variables that will be used as we 
progress. The new variables to add are ac and selection . The first is for 
the ApplicationControiler instance, which we will delve into later in the 
chapter. The second is used to track the user’s current date selection. 
The complete definition, including variables defined in Chapter 7, is: 

Object subclass: #CalendarWindow 

i nstanceVar-' abl eNames : 'ac dates calendar shell weekdays selection' 
classVariableNames: '' 

poolDictionaries: 'CwConstants CgConstants ' 

Next, what we need to do is modify the method addDatesRegion so 
that the labels all include the following: 

aButton 

addEventHandler: ButtonPress 
receiver: self 

selector: #buttonPress:clientData:callData: 
clientData: nil. 
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This code should go into the loop after the third line in the loop, 
“argBlock: nil.” Once you’ve inserted it, create the event handler method 
named above. This simple method looks like: 

buttonPress: aButton clientData: aDay cal 1 Data: callData 

"Private - A ButtonPress event has occured in the Calendar." 
CgDisplay default bell:10. 

The last line of the method will ring the bell each time a label is clicked 
— at least we hope it will. Why don’t you close the door, so you won’t 
disturb anyone? For those of you in cubicles, just don’t test too long. 

We are ready for our test. Run the Calendar Application and then 
click on any of the dates. How about that! It works. That was easy, and in 
fact we have nearly all the code installed we will need for the final prod¬ 
uct. Not bad for a little noise. 

Responding to the Button Press Event 

We can now concentrate on how we want to handle the event. We want 
to use the label widget’s label string to supply the date the user selected, 
but we need to define a method for Calendar to handle this selected date 
as we wish. The selected date will be a string containing only the day 
number, since that is what the user selects. This will actually be the 
selected label’s label string. The month and year haven’t changed, how¬ 
ever, and we know them, so we can simply use the Calendar method 
makeNewDate: that we created in Chapter 7. Of course, we will need a 
way to set and get the Calendar class day variable, which we’ll get to in 
a moment. We can let CalendarWindow update the calendar with its 
highlightCalendar method, exactly as it now does. 

Here, then, is the instance method dateSelected: to be added to 
CalendarWindow class: 

dateSelected: aString 

"A date was selected update calendar and 
myself" 

| label | 

aString = ' ' ifTrue: [ A self]. 
calendar day: aString asNumber. 
selection := aString. 
self highlightCalendar. ] 
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The number of the day selected is passed as an argument and a new date 
is generated, just as we required. The instance variable selection will be 
used to store the current selection. We also check for an invalid selection 
such as from one of the spaces at the top or bottom of the calendar. Be sure 
to leave a space between quotation marks, making it ’ not ”. As you may 
have guessed ; we will be visiting this method again later. 

We need to go back to the buttonPress: method and update it to do 
some work, instead of just making noise. Here is the modified method: 

buttonPress: aButton clientData: aDay cal 1 Data: cal 1 Data 

"Private - A ButtonPress event has occured in the Calendar." 
self dateSelected: aButton labelstring. 

Notice we get the string by requesting it from the widget passed as 
the first argument of the method. With this step complete, we should 
update the Calendar class to meet our new requirements. We will use 
another tool from the classes browser to make this almost effortless. 

Click on the Calendar class. Then, from the instance methods list, 
select instance variables. All the instance variables will now be displayed 
in the list. Select the day instance variable then, from the pop-up menu, 
select Generate Accessors. Name the argument whatever you like, but 
be nice. The methods have been generated. All we need to do now is add 
the line self makeNewDate to the day: method. 

That’s all there is to it. We can now select all the dates we want. 
However, it would be better if we could see our date selection. We al¬ 
ready know how to highlight the labels; maybe we could highlight the 
selected day. The problem is, it would be hard to see holidays, appoint¬ 
ments, and today highlights if we used another highlight. What if we 
were to highlight the date by setting a background color? Then we 
wouldn’t be disturbing our existing highlights. In the next section we 
will do exactly this. 

Now that we’ve defined a way for the user to select dates on the calendar, 
it would be nice if a date would remain highlighted as the user navigates 
through the calendar. We could have used the highlighliforeColor: method 
to turn the date’s color into what we want. We decided a background color 
would be more quickly recognized. It turns out this approach is pretty easy 
to implement; all we have to do is use the method backgroundColor: instead 
of foregroundColor:, and IBM Smalltalk will do the rest. 

We want to use this approach not only for holidays but for any day we 
want to highlight as the user navigates through the calendar. So we’ll name 
this method highlight:withBackColor: and base it on the existing method 
highlight:with: . Here’s the code for this addition to CalendarWindow: 
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highlight: aString withBackColor: aColor 

"highlight the date represented by aString with a aColor. " 

| date string | 
string := aString isString 
ifTrue: [ aString] 
ifFalse: [aString printSt ring]. 

date := dates children detect: [:c | c labelstring = string]. 

We should create a class method in CgRGBColor that will provide a 
gray color. Here is the class method with a color we found worked well: 

gray 

"answer the color gray" 

A self red: 65535 green: 30000 blue: 30000. 

As a final step in this process of generalizing the highlighting meth¬ 
ods, we need to modify the highlightCalendar method to use our new 
highlight and color methods. Here is the new method: 

highlightCalendar 

"highlight the appropriate dates in the calendar" 

| today holidays appts| 
holidays := calendar showHolidays. 

holidays do: [:h | self highlight: h dayOfMonth with: CgRGBColor 
red]. 

selection notNil ifTrue: [ 

self highlight: selection wi thBackCol or: CgRGBColor gray], 
calendar showToday 

ifTrue: [ today := calendar today, 
self highlight: today dayOfMonth with: CgRGBColor green, 
(weekdays children at: today daylndex) foregroundColor: 
CgRGBColor green. 

]. 

We check to make sure we have a valid selection before we highlight 
it, because clicking on an unlabeled space in the calendar will also re¬ 
sult in a button press, which we want to ignore. 

The selected date will always be visible as the user clicks through the 
calendar. Since we decided to use the background color and selection high¬ 
lighting, the special dates’ colors will show through. This approach avoids a 
conflict between showing that a date is the selected date and a special date. 
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Removing fie Highlight 

Now that we can set a date’s background color, we need to make sure 
that we turn it off again when another date is selected. This consider¬ 
ation will require us to modify the method dateSelected: in the 
Calendar Window class. Since this is where we set the highlight, it seems 
logical it should be removed here as well. We use the instance variable 
selection to track the selection made. It is a simple matter of setting the 
color of the date held in this variable back to white before it is set by the 
next selection. Here is the code, with modifications in bold: 

dateSelectec : aString 

"aDa:e was selected update calendar and 
myself" 

| label | 

aString = ' ' ifTrue: [ A self]. 
calendar day: aString asNumber. 
selection notNil ifTrue: [ 

self highlight: selection withBackColor: CgRGBColor white]. 

selection := aString. 
self highlightCalendar. 



Appointment BookWindow is the class most affected by the change from a 
single-window, single-purpose calendaring application to a multi-windowed, 
multi-purpose application including an appointment book. That’s because 
it is a class that will create and manage the new windows widget tree. 

In a sense, then, everything in this chapter so far is a prelude to changes 
we are about to make to AppointmentBookWindow to put the finishing 
functional touches on our increasingly robust and complex application. 

We need to make several kinds of changes to our application before 
we can get it working. These changes include: 

■ Adding appropriate instance variables to the AppointmentBook¬ 
Window class definition 

■ Adding appropriate widget creation methods for the components of 
the window 

■ Modifying the open method to call the new methods 

m Ensuring that both the calendar window and the appointment book 
window close when either of them is closed 
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m Ensuring that both the calendar window and the appointment book 
window appear when either of them is activated 
m Creating Edit and Appointment menus for the AppointmentBook- 
Window menu bar and adding the appropriate callback methods 
for each menu item 

Adding Needed Instance Variables 

The AppointmentBookWindow needs eight variables: one to store the 
AppointmentBook instance, one for the application controller that we’ll 
discuss later, and the others for the widgets it contains. 

Here is what the object definition for AppointmentBookWindow will 
look like after you’ve added the new instance variables called apptBook, 
ac, shell, schedule, text, start, end, and holiday. 

Object subclass: #AppointmentBookWindow 

instanceVariableNames: 'apptBook ac shell schedule text start end 
holiday ' 

classVariableNames: '' 

poolDictionaries: 'CwConstants CgConstants ' 


Modifying the AppointmentBook Window 
Open Method 

Our SimplePIM application is growing, so we need to bring over some of 
the methods we created for the CalendarWindow to our new window. 
Let’s start with the open method from CalendarWindow, since it makes 
a good place to start the AppointmentBookWindow’s open method. Copy 
the method from CalendarWindow and paste it into a new instance 
method for the AppointmentBookWindow. You will have the following: 

open 

"open a Calendar on today's date" 

| main form text rowColumn | 
self setup. 

shell := CwTopLevelShel 1 

createApplicationShel1: 'Calendar Example' 
argBlock: nil. 
main := shell 


createMainWindow: 'main 
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a r g B1o c k : nil, 
main manageChild. 

self addMenuBar: main, 
form := main 

createForm: ’form' 
a r g B1o c k: nil. 
form manageChi1d. 

self addButtons: form, 
self addWeekdaysRegion: form, 
self addDatesRegion: form. 

shell realizeWidget. 

We know we will have new region methods, so remove the code that 
defines these regions, except the reference to addMenuBar :. We will need 
that method since the AppointmentBookWindow will have one. Move 
the reference to self setUp code to the bottom of the method. We will try 
it there first. 

Now we are ready to jump feet first into the child widget creation 
code. We need methods for the text widget, the list widget, and several 
label widgets. We will call these methods addText:, addScheduleList :, 
and addLabels respectively. 

A Little Landscaping Never Hurts the Tree 

As we learned in Chapter 7, it behooves us to plan our window a little 
before jumping into coding. With widgets, this means thinking about 
attachments, who and where. 

Let’s think about our widgets a bit. Which one must be added to the 
form first? The list will be attached to the far left and top sides of the 
form. The right side of the list will be attached to the text widget. The 
right side of the text widget will attach to the right side of the form. 

That sounds good. Now, where should we put the labels? We will have 
one label each for the current appointment start time and end time and 
one for the holiday description. You probably guessed this from the classes 
definition. Let’s put the labels above the list and text widgets. We will 
connect the start and end labels to each other and place the holiday 
label directly below them (as displayed in Figure 9-1). 



Start 

End 

Holiday 

List 

Text 


Figure 9-1. 


Widget placement for AppointmentBookWindow 


While this label placement looks all right, a label over the list indicat¬ 
ing it is the schedule would look better. After moving things around a bit, 
we end up with a configuration like Figure 9-2. 
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List 

Holiday ' 

Text 


Figure 9-2. 


The final widget layout for AppointmentBookWindow 


Now the list has its own grouping, and the appointment elements are 
grouped together as well. With a picture of how our widget tree will fit 
together, we can now develop some code. Judging from our description 
of the widget tree, it appears best to start with the four labels. 

The next question is which forms to use. The start and end labels would 
probably work best attached to a rowColumn form widget, while the other 
two label widgets will attach to the main form. Armed with this knowledge, 
we know we can get a head start on this method by stealing the code from 
the CalendarWindow addDatesRegion: method. Copy the method into the 
AppointmentBookWindow class. Starting with this method we have: 
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addDatesRegion: form 

"Private - Create the receiver's Dates region 
where the date labels are displayed." 

| aRowColurn aButton dashes | 

"Create the RowColumn." 

(dates : = aRowColumn := form 
createRowColumn: 'RowColumn' 
argBlock: [:w | w 
marginHeight: 5; 
margin Width: 5; 
numColumns: 6; 
orientation: XmHORIZONTAL; 
packing: XmPACKCOLUMN; 
entryAlignment: XmALIGNMENTEND; 
radioBehavior: false; 
adjustLast: false; 
spacing: 7]). 

"Add some buttons to the RowColumn." 

1 to: 42 do: [:i | 

aButton := aRowColumn 
createLabel: 'button ' 
a ^gB 1 ock: nil. 
aButton 

addEventHandler: ButtonPress 
receiver: self 

selector: #buttonPress:clientData:callData: 
clientData: nil. 

aButton manageChi1d]. 

aRowColumn manageChild. 

self updateCalendar. 

aRowColumn setVa1uesBlock: [:w | w 

topAttachment: XmATTACHWIDGET; topWidget: weekdays; top0ffset:0; 
bottomAttachment: XmATTACHFORM; 

1eftAttachment: XmATTACHFORM; 
rightAttachment: XmATTACHFORM]. 
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We can remove the loop completely, along with the line following the 
loop. The rowColumn definition is similar to what we need except that it 
has zero margins and only one column, whereas it should use center 
alignment and have no spacing. Make those changes. 

The attachment block for the rowColumn needs some modifications 
as well. First, we don’t want a bottom attachment, or it will stretch over 
the text widget. Second, the widget we want to attach to is on the left, 
not the top. Here is the modified code segment: 

aRowColumn setValuesBlock: [:w | w 
topAttachment: XmATTACHFORM; 

1eftAttachment: XmATTACHFORM; leftWidget: label; 
rightAttachment: XmATTACHFORM]. 

Between the last two pieces of code, we place the label creation code: 

start := rowColumn 
createLabel: ' start' 
argBlock: [:w | w 

labelstring: ' Start: 08:30 AM '; 
recomputes!ze: false; 
borderWidth: 1]. 
start manageChild. 

end := rowColumn 
createLabel: 'end' 
argBlock: [:w | w 

labelstring: ' End: 10:30 AM '; 
recomputeSize: false; 
borderWidth: 1 ]. 

end manageChild. 

The important thing to note here is that we told the widget not to 
change size based on the label string size and that we provided a tem¬ 
plate to set the initial size of the label. Finally, each label will have a 
border so it will look like our earlier sketches. The code segments assign 
the resulting widgets to the predefined instance variables start and end. 
Assigning these widgets to instance variables will make it easy to access 
them when we need to make changes. 

We can copy the code we created for the above widgets and use them 
to create the remaining label widgets. Assign the holidays widget to the 
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instance variable of the same name and the schedule label widget to the 
temporary variable label. The resulting code should look similar to this: 

addLabels: aForm 

"add the schedule, start, end and holiday labels" 

| label rowColumn | 
rowColumn := aForm 

createRowCol umn: 'labels' 
argBlock: [:w | w 

marginHeight: 0; 
marginWidth: 0; 
numCol unins: 1; 
orientation: XmHORIZONTAL; 
packing: XmPACKCOLUMN; 
entryAlignment: XmALIGNMENTCENTER; 
racioBehavior: false; 
adjustLast: true; 
spacing: 0 ]. 
rowColumn manageChild. 
label := aForm 

createLabel: 'Schedule' 
argBlock: [:w | w 

labelstring: ' Schedule '; 
borderWidth: 1 

]. 

label manageChild. 

start :=rowColumn 
createLabel: ' start' 
argB1ock : [:w | w 

labelstring: ' Start: 08:30 AM '; 
recomputeSize: false; 
borderWidth: 1]. 
start manageChild. 

end :=rowColumn 
createLabel : 'end' 
a rgB1ock: [:w | w 

labelstring: ' End: 10:30 AM '; 
recomputeSize: false; 
borderWidth: 1 ]. 


end manageChild. 
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ho1iday := a Form 

createLabel: 'hoi 1 day' 
argBlock: [:w | w 

labelstring: ' ' ; 

alignment: XmALIGNMENTCENTER; 
foregroundColor: CgRGBColor red; 
recomputeSize: false 
borderWidth: 1]. 
holiday manageChi1d. 
rowColumn setValuesBlock: [:w | w 
topAttachment: XmATTACHFORM; 

1eftAttachment: XmATTACHWIDGET; leftWidget: label; 
rightAttachment: XmATTACHFORM]. 

The last step is setting the attachments of these newly added widgets. 
Remember, the widgets in the rowColumn widget won’t have any attach¬ 
ments, since this is handled for them by this form widget. Here is the 
final code segment for this method: 

label setValuesBlock: [:w | w 

topAttachment: XmATTACHFORM; 

1eftAttachment: XmATTACHFORM]. 
holiday setValuesBlock: [:w | w 

topAttachment: XmATTACHWIDGET; topWidget: start; 

1eftAttachment: XmATTACHWIDGET ; leftWidget: label; 
rightAttachment: XmATTACHFORM]. 

Notice that the holidays label attaches to two widgets, the start wid¬ 
get in the rowColumn and the label widget. 

Adding the List Widget to the Window 

We are quite familiar with label and button widgets, but we have not 
had any experience with the list widgets. There’s a variety of widgets to 
choose from: combobox or composite box widgets, which combine a text 
field and a list; selection box widgets, used in dialogs to permit the user 
to choose from a variety of items; or the standard list. It is the standard 
list we are interested in. 
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You can work with the other list types by running their examples. The easiest way to 
do this is to execute the code "CwExamplelauncher new open." By the way, most of 
the examples in the CwExamples application have comments associated with their 
classes that tell you how to launch them and give an explanation of their function. 



The standard list has several flavors of item selection: single select, 
multiple select, extended select, and browse select. They differ in the 
way they allow the user to select from the list. The first allows only one 
selection; the next, multiple selections, but no deselection; the third, 
multiple selection with deselection; and the last, the ability to select by 
dragging the mouse. For our purposes we will stick to a standard single 
selection list. 

The XmNsingleSelectionCallback callback will notify us when a selec¬ 
tion has been made. We will assign this to our own selector appointment - 
Selected:clientData:callData:. The widget will be assigned to the instance 
variable schedule. Again, the attachment will be the greatest concern. 
We need to make sure the list fits snugly against the left side of the form, 
the top of the schedule label, the left side of the holiday label, and the 
bottom of the form. Here is the addScheduleList: method in its entirety: 

addSchedul el_i st: aForm 
schedule := a Form 

createScml 1ed L i st: 'list' 
argBlock: [:w | 
w 

visibleltemCount: 10; 
selectionPolicy : XmSINGLESELECT ]. 
schedule manageChild. 

schedule 

addCal1 back: XmNsingleSelectionCallback 
receiver: self 

selector: #appointmentSelected:clientData:callData: 
clientData: nil. 

schedule parent setValuesBlock: [:w | w 

topAttachment: XmATTACFIWI DGET; topWidget: start; 
bottomAttachment: XmATTACFIFORM; 

1eftAttachment: XmATTACHFORM; 

rightAttachment: XmATTACHWIDGET; rightWidget: holiday]. 
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We should point out that the attachments above were made to the 
parent of the widget, not the widget itself. This is because this is a scroll¬ 
ing widget and, as such, the list is created as a CwList with a CwSrollBar 
widget added to it. The form should attach to the CwScrollBar widget 
since the CwList is its child and, in turn, is attached to it. But the cre¬ 
ation method returns the CwList object, so you must send the message 
parent to this object in order to set the attachments. 

Adding the Text Widget 

Next on our list is the text widget. Text widgets are quite complete and 
provide support for editing, inserting, and deleting text. On some plat¬ 
forms, most notably OS/2, they even support wrapped text. Text widgets 
can be single line or multiple line and scrolled or not. To put text into the 
widget, you use the message setString:. Contents of the text widget can 
be retrieved with the message getString. 

That’s enough information on which to build our first text widget. The 
method is actually quite simple except for the attachments. We again 
assign the widget to an instance variable for easy access. The complete 
method follows: 

addText: aForm 

"Add a text widget to me" 
text := aForm 

createScrol1edText: 'text' 
argBlock: [:w | w 

editMode: XmMULTILINEEDIT; 
scrol1Horizontal: false; 
wordwrap: true 
]. 

text manageChi1d . 

text parent setValuesBlock: [:w | w 
topAttachment; XmATTACHWIDGET; topWidget: holiday; 
bottomAttachment: XmATTACHFORM; 

ri ghtAttachment: XmATTACFIFORM ; 

1 eftAttachment: XmATTACHWIDGET; 1eftWidget: schedule]. 

Notice once again that we need to set the attachments to the parent, 
since we are working with a scrolling widget. The widget’s top is at- 
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tached to the holiday label; its bottom and right, to the form; and its left, 
to the list widget. In order for wordwrap to work, the horizontal scroll 
bar must be turned off. 

Getting Items from the List and Text Widgets 

Before we forget, we should create the callback method for the list. This 
method will save the text contents, determine which appointment the user 
has selected, and display its entry in the text widget. Here is the method: 

appointmentSelected: widget clientData: ignore cal 1 Data : data 
"A se'ection has been made in schedule list 
so notify apptBook and display new 
entry" 

self save Entry. 

apptBook appointmentstarting: data item, 
self display Entry. 

This method uses the AppointmentBook that was defined previously 
as apptBook, along with two undefined methods. Let’s produce these 
two simple methods before we forget. These methods use methods we 
created in the AppointmentBook class. The first uses the text widget’s 
access method getString to save the current text contents as the current 
appointment's entry. It is coded as follows: 

saveEntry 

"Save the text as an appointment entry" 
apptBook saveEntry: text getString. 

The second method sets the contents of the start, end, and text wid¬ 
gets. The method is just as easy to code as the last and relies on the 
methods created in the AppointmentBook to display elements of the 
current appointment. The method is: 

displayEntry 

"display entry in text and set labels" 
start labelstring: 'Start: '.apptBook startTime. 
end labelstring: 'End: ', apptBook endTime. 
text setstring: apptBook entry. 
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Setting the List 

In addition to taking items from the list, we also need to be able to re¬ 
fresh the list with new appointments when a different date is selected. 
The following method does just that: 

setSchedule: aCollection 

"set the schedule list to aCollection" 
self clearEntry. 
schedule items: aCollection. 
schedule deselectAl11 terns. 

Analyzing the method, we see an undefined method and two list meth¬ 
ods. We will get to the two list methods later. While we have it in our 
thoughts, let’s add the clearEntry method: 

clearEntry 

"clear my entry text and labels" 
start 1abelString: ' '. 
end labelstring: ' '. 
text setString: ' '. 

As for the list methods, items: obviously sets the list, but the reason 
for using deselectAllItems is not so evident. This method ensures that 
when we change dates the new list has no selection. 

As it turns out, unless you explicitly turn off the selection, the list will 
select any list items matching the last selection. This means that if the last 
appointment start time selected by the user was “8:30 AM,” then the list 
selects each appointment with the same start time for each date selected by 
the user. This is not very desirable, since the selection is not consistent 
between dates. It becomes hard to know when to display data and when to 
clear. The deselectAllItems method makes sure no selections will be made 
in the list except by the user; it results in a consistent interface. 

Adding the Two Menus to the Menu Bar 

Copying and editing the CalendarWIndow addMenuBar: method will 
speed the development of the final widget tree creation method, also 
called addMenuBar:. 

As you may recall, in the Calendar Application, the menu bar con¬ 
tained only one menu, which itself contained a submenu. For the new 
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method we want two menu bar menus. We have no need for a submenu. 
We should be able to change the existing method simply by reassigning 
the creation and use of the submenu. Let’s take a look at the original 
method from the class Calendar Window: 

addMenuBar: aMainWindow 

"Add the 5 menu buttons to the window" 

| monthAhead yearAhead today monthBack yearBack menuBar form 
submenu subMenu2 form2 
gotoMY refresh | 

menuBar:=aMainWindow createMenuBar: 'menu' 
argBlock : ni1 . 
menuBar manageChild. 

form := menuBar createPul1downMenu: 'pulldown' 
a rg B1ock : nil. 

subMenu:=menuBar createCascadeButton: 'Calendar' 
argBlock: [:w| w subMenuId: form]. 
subMenu manageChild. 

form2 := form createPul1downMenu: ' pu112' 

argBlock: nil. 

subMenu2 :=form createCascadeButton: 'Look' 
argBlock: [:w| w subMenuId: form2]. 
subMenu2 manageChild. 


monthAhead := form2 

createPushButton: ' Month Ahead ' 
argBlock: nil. 

monthAhead addCallback: XmNactivateCa11 back 
receiver: self 

selector: #monthAhead:clientData:callData: 
clientData: nil. 
monthAhead manageChild. 

yearAhead := form2 

createPushButton: 'Year Ahead' 
argBlock: nil. 

yearAhead addCallback: XmNactivateCal1 back 
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receiver: self 

selector: #yearAhead:clientData:callData: 
clientData : nil. 
yearAhead manageChild. 

today := form 

createPushButton: 'Today' 
argBlock: nil. 

today addCal1 back: XmNactivateCa11 back 
receiver: self 

selector: #today:clientData:callData: 
clientData: nil. 
today manageChild. 

yearBack := form2 

createPushButton: 'Year Back' 
argB1ock: nil. 

yearBack addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #yearBack:clientData:callData: 
clientData: nil. 
yearBack manageChild. 

monthBack := form2 

createPushButton: 'Month Back ' 
argB1ock: nil. 

monthBack addCallback: XmNactivateCal1 back 
receiver: self 

selector: #monthBack:clientData:callData: 
clientData: nil. 
monthBack manageChild. 

gotoMY := form 

createPushButton: 'Go to Month and Year' 
argBlock: nil. 

gotoMY addCallback: XmNactivateCal1 back 
receiver: self 

selector: #gotoMonthYear:clientData:call Data : 
clientData: nil. 
gotoMY manageChild. 
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refresh := form 

createPushButton: 'Refresh' 
argBlock: nil. 

refresh addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #updateCalendar:clfentData:cal 1 Data: 
clientData : nil. 
refresh manageChild. 

One of the first things you may want to do is use a single temporary 
variable for the buttons. Use it to replace all those currently assigned. 
This change will help avoid confusion later when you are trying to deter¬ 
mine what this code does. The names are a historical leftover from when 
we used the addButtons: method to create this method. Since no attach¬ 
ments are made in a menu, separate names are not a requirement. Re¬ 
place the code: 

subMenu2 :=form createCascadeButton: 'Look' 

argBlock: [:w| w subMenuId: form2]. 
subMenu2 manageChild. 

with the code: 

subMenu2 :=menuBar createCascadeButton: 'Appointment' 
argBlock: [:w| w subMenuId: form2]. 
subMenu2 manageChild. 

With this simple change we have moved the menu to the menu bar. 
(Aren’t widgets cool?) Which menu a menu item is assigned to is deter¬ 
mined purely by the pull-down menu used to create it. If we use form , 
the button is on the Edit menu. On the other hand, form2 places a button 
on the Appointment menu. All that is left to do is to assign each button a 
proper label and callback method. We don’t need the last button labeled 
“refresh,” so remove that code. The resulting method is displayed below: 

addMenuBar: aMainWindow 

"Add the Edit and Appointment menus" 

| item menuBar form subMenu subMenu2 form2 | 

menuBar:=aMainWindow createMenuBar: 'menu' 
argBlock: nil. 
menuBar manageChild. 
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form := menuBar createPul1downMenu: 'pulldown' 
argB1 ock: nil. 

subMenu:=menuBar createCascadeButton: 'Edit' 
argBlock: [:w| w subMenuId: form]. 
subMenu manageChild. 

form2 := menuBar createPul1downMenu: 'pu112' 

argB1ock: nil. 

subMenu2 :=menuBar createCascadeButton: 'Appointment' 
argBlock: [:w| w subMenuId: form2]. 
subMenu2 manageChild. 


item := form 

createPushButton: 'Cut' 
argBlock: ni1. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #cutText:clientData:callData: 
clientData : nil. 
itern manageChi1d . 

item := form 

createPushButton: 'Copy' 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #copyText:clientData:callData: 
clientData: nil. 
item manageChild. 

item := form 

createPushButton: 'Paste' 
argBlock : ni1. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #pasteText:clientData:call Data: 
clientData: nil. 
item manageChild. 
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item := forni2 

createPushButton: 'New' 
araBlock: nil. 

item a :idCa 11 back: XmNacti vateCal 1 back 
receiver: self 

selector: #new:clientData:cal!Data: 
clientData: nil. 
item manageChi1d . 

item := form2 

createPushButton: 'Delete' 
argBlock: nil. 

item acdCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #delete:clientData:cal 10ata: 
clientData : nil. 
i tern manageChi1d . 

item := form2 

createPushButton: 'Save' 
argB1ock: nil. 

item addCal 1 back: XmNactivateCal1 back 
receiver: self 

selector: #save:clientData:callData: 
clientData : nil. 
item manageChi1d . 

Next, you should create methods for these menu items based on the names 
supplied with the callback definition. These will be skeleton methods con¬ 
sisting of a name, arguments, and comment only. We will develop the code 
for these later. 

The final step in the creation of the widget tree is changing open so it 
will call these new methods. After the statement 

form manageChild 

add the following method code: 


self addLabels: form, 
self addScheduleList: form, 
self addText: form. 
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Copy the setUp method and change the code to look like this: 

setup 

"setUp apptBook" 

apptBook := AppointmentBook new. 

We will revisit this method again later after we have created our Ap¬ 
plication Controller framework in the next section. 

This approach sure makes it easy to create a new class. Always look 
for ways to copy code rather than write new code, especially if it is code 
that has been have tested and that you know works. 



Well, our little application is growing and so is the number of windows. 
We need to put together a framework for managing multiple windows. 
As explained in Chapter 8, the framework is based on the Object class 
variable, Dependents. 

A dependent object, which well call D for this discussion, makes itself 
a dependent of another object, which we’ll call 0, by adding itself to O’s 
dependent objects. Normally you have to have direct access to an object 
to which you wish to send messages, but this framework lets an object 0 
broadcast a message to all dependents including D. Object 0 does not 
need to know about object D in order to send it messages. 

To better utilize the dependency framework, we will create a new 
class called AppIieationController, an instance of which will be respon¬ 
sible for managing the framework and the applications. 

The ApplicationController Class 

Why a new class? First, although object 0 does not need to know about 
object D in the normal dependency design, object D does need to know 
about object 0. This is not a desirable trait since it still requires the 
objects to have knowledge of each other. The Application Controller will 
hide instances of objects from each other and allow us to gain access 
through a well-known set of methods. 

Second, while broadcasts can handle events, they are not very useful 
for the second form of inter-window communication, information pass¬ 
ing. It is difficult to use a broadcast to direct a message to a particular 
instance from which you need data. The Application Controller can serve 
as a publisher and provider of information. 
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Third, the Application Controller can serve to synchronize events, such 
as activating and closing a given set of applications’ windows. By group¬ 
ing these events under the Application Controller, applications can be 
isolated from repetitive event activations, which, under normal circum¬ 
stances and left to their own devices, would lock up your system. 

Last but not least, this new class can provide group-based application 
services, such as launching all applications related to one another. Without 
the Application Controller the applications would have to coordinate this 
among themselves, again requiring their specific knowledge of one another. 

Defining the Class 

The task of controlling applications will be handled by the Application- 
Controller class, an Object subclass. The class is defined as follows: 

] Object subc'ass: #Appl i cat.i onControl 1 er 
flistanceVariableNames: 'applications' 
classVariableNames: ’' 
poolDictionaries: '' 

The instance variable applications is a Dictionary with a symbol called 
type as the key and the application itself as the value. This scheme al¬ 
lows us to assign applications under a well-known keyword without re¬ 
vealing the application itself. The highly anticipated initialize method 
this time reads as: 

initialize 

"set up the AC" 

applications := Dictionary new: 10. 

Have no fear, new: 10 does not limit us to ten applications; it merely 
causes the dictionary to start with a smaller than normal size. The even 
more highly anticipated new method should be defined next, but since it 
differs not one bit, byte, or word from the other new methods we have 
defined, we will leave it to you. 


Devising the Framework 

For the Application Controller to be easy to use, it should handle most of 
the work of se tting up dependencies, including keywords, and launching 
applications. These tasks are accomplished by the method setAppli- 
cation:type:, whose code is: 
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setApplication: aClassSymbol type: aSymbol 

"set aClassSymbol as an appplication and 
set me as Application Controller" 

I app | 

app := (Smalltalk at: aClassSymbol) new. 
self addApplication: app type: aSymbol. 
app controller: self. 

A app 

This method requires some explanation. The first line accesses the 
Smalltalk dictionary, where all classes and global variables are defined. 
The method will return an actual IBM Smalltalk class object, not just its 
name. With the class object we can create an instance of the class, which 
we do. Next, some undefined methods are used to add the application to 
the dictionary, and to assign the Application Controller to the applica¬ 
tion. We answer the created application for the sake of convenience. 
The method addApplicatiomtype: is written as follows: 

addApplication: anApplication type: appType 

"Add anApplication to the applications list under the key appType" 
A a pp1ications at: appType asUppercase put: anApplication . 

To avoid problems with case errors, the keyword is stored in upper¬ 
case. The controller: method is actually an application we will define 
when we add the framework to individual applications. 

The setApplicationitype: method is designed to be used with another 
method we call launch. This latter method is a convenient place to de¬ 
fine your group of related applications. Here is the method with our two 
applications defined: 

launch 

"launch the applications I control. Each Application to be opened 
should appear here" 

| a pp1 app2 | 

"assign keyword to each application" 

appl := self setApplication: #CalendarWindow type: ^Calendar. 
app2 := self setApplication: #AppointmentBookWindow 
type: #AppointmentBook. 

"ready to launch all apps; open is assumed to be the starting 
method" 

self startApplications. "Starts all apps" 
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"finally set up each app's dependency framework" 

self application: appl hasInterestlnType: #AppointmentBook. 

self application: app2 hasInterestlnType: ^Calendar. 

As a resul t of this scheme, we don’t have to modify any existing appli¬ 
cation methods to install the framework. We will, of course, have to cre¬ 
ate a few new ones. You should note that the positioning of each section 
is critical to the proper running of the code. We must first create new 
application instances, then start the applications and finally, describe 
their dependency. To do these things in any other order would get things 
out of synch. 

Once again, we have a couple of methods to define before this method 
can be used. The startApplications method is easiest to code, so we will 
start with it. 

sta rtApplications 

"Start all my applications 
Assumes open starts an app" 
applications do: [:a | a open; resetActivate]. 

We will discuss the method resetActivate later. 

The dependency setup method application:hasInterestlnType: per¬ 
forms its task like this: 

application: anApp hasInterestlnType: appType 
"add application as a dependent of the 
appl’cation appType" 

I app | 

app := self getApplicationOfType: appType. 
app not Nil ifTrue: [ 

app addDependent: anApp 

]. 

This necessitates developing another method. Does it sometimes feel 
like we are moving backwards? This method is responsible for retriev¬ 
ing applications from the dictionary. Here is its code: 

getAppl i cati c-nOfType : appType 

"answer the application with type appType, if application 
does not exist answer nil " 

Appl ications at: appType asllppercase ifAbsent: [ A ni 1 ]. 
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Notice we again convert to uppercase to avoid case sensitivity. We 
need one more framework method to remove the application along with 
its keyword and dependencies. This method will be called by an applica¬ 
tion when it closes. The method code is: 

removeApplicationType: appType 

"Remove the application keyed under appType 
and any any dependencies it has" 

I app | 

app := applications removeKey: appType ifAbsent: []. ] 
app release, 
app notNil 

ifTrue: [ applications do: [:a | a removeDependent: app]]. 

Finally, to make application launches even easier, we will provide a 
class method. Here is the method: 

1aunch 

"create a new AC and open app windows" 

A self new launch 


Methods Requesting information 

One of the main reasons for the Application Controller framework is to 
allow applications to make requests of each other using keywords. There 
are three methods defined for this job. Each builds on the other. We will 
start with the easiest code first. The method reads: 

request: aSymbol from: appType 

"Answer the result of sending the application of appType the 
message aSymbol" 

I app | 

app : = self getApplicationOfType: appType. 
app isNiJ ifTrue: [ A ni1]. 

(app respondsTo: aSymbol) 

ifTrue:[ A app perform: aSymbol]. 
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The first two lines contain familiar code. However, the third and fourth 
lines require some description. In the third line, we check to see if the 
application we targeted supports the message we sent and, if so, we 
continue in the fourth line and use the perform: method (defined in class 
Object) to execute the requested method. The perform: method acts some¬ 
thing like a batch file and treats the selector like an executable file. The 
result of the message is returned to the receiver or, if we failed for some 
reason, nil is returned. 

The second method is the same as the one above except for its name 
and the fact that it uses perform:with:, a version of the perform: method 
that passes an argument along with the message. Here is the method: 

request: a Symbol from: appType with: anObject 

"Answer the result of sending the application of appType 
message eSymbol with argument anObject. aSymbol must 
be able to take parameter" 

I app | 

app :» self getApplicationOfType: appType. 
app is Nil ifTrue: [ A nil]. 

(app respondsTo: aSymbol) 

ifTrue:[ A app perform: aSymbol with: anObject]. 

A n i 1 . 

We will be able to use the above method to send an object, such as a 
Date, along with our request. The third and last version of this method 
set will pass a collection of arguments, not just one. While we have no 
obvious need for this method right now, we will provide it in an attempt 
to make the class more generic. The method is coded: 

request: aSymbol from: appType withArgs: aCollection 
"Answer the result of sending the app of appType 
message aSymbol with arguments aCollection. aSymbol must 
be able to take parameter" 

I app | 

app := self getApplicationOfType: appType. 
app isNi1 ifTrue: [ A ni1 ] . 

(app responjsTo: aSymbol) 

ifTrue:[ A app perform: aSymbol withArguments: aCollection]. 

A ni 1 . 
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Avoiding Dueling Windows 

We want our application to work so that both CalendarWindow and 
AppointmentBookWindow will be open at the same time, and so that 
when one of them is activated, its “partner” is also activated. Handling 
this task is a bit trickier than it may seem at first. Here’s the method, 
called applicationActivated :, which is the central manager of this task; 
it is called by a window when its activate callback is detected: 

applicationActivated: anApp 

"an application has activated, so activate all others" 
(applications reject: [:a | a = anApp]) 
do: [:a | a activate]. 

anApp activate. 

[(Delay forMi11iseconds: 10) wait, 
applications do: [:i | i resetActivate]] fork. 

First, the activating application is passed as an argument to the 
ApplicationController class to track the active window. This is impor¬ 
tant because we don’t want our windows flashing back and forth as they 
fight to be the active window. We have another catch-22 situation (you 
will find almost as many of these in programming as in the army); this 
time it deals with recursive signaling. Our framework says that when a 
window is activated it will signal the Application Controller, and the Ap¬ 
plication Controller will in turn bring the other windows forward and 
show them. Guess what else this does? Right. It makes those windows 
active, and they in turn signal the Application Controller, which then 
brings all the other windows forward and shows them and they in turn... 
well, you get the idea... flashing syncopated windows. Just add music, 
sit back, and enjoy. 

Unfortunately, we have to create serious software, so what do we do? 
We need a way to isolate the Application Controller and its applications 
from additional focus callbacks. To make things even more difficult to 
handle, it turns out the focus callback is signaled for both losing and 
gaining focus. This means we have double the number of callbacks to 
handle. That’s where applicationActivated: comes in. It’s our way of 
determining who started the whole thing—and blocking any additional 
attempts to signal the Application Controller—until all windows are 
brought to the front and things have settled. Additional sends of this 
message are blocked by removing the focus callback. Once we are in this 
method, we no longer accept signals. We are now free to sequence through 
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the rest of the windows and bring them to the front. When we are done, 
we tell the active window to come to the front. This may seem strange, 
but after all the shuffling is done, we want to make sure the active win¬ 
dow is the one in which the user clicked. 

You may be wondering when callbacks are restored. One very impor¬ 
tant aspect of dealing with recursive sections of code is to make sure 
that the controlling entity is manipulated outside of the recursive sec¬ 
tion. If we were to add callbacks too early, we would be no better off. We 
would start a new loop of signals in the middle of the existing one, which 
is exactly what we are trying to avoid. Without the callbacks being re¬ 
stored, the application windows cannot respond to the window activa¬ 
tion. So where do we restore the callback? 

We cannot use an event because we would be dependent on the user 
doing some task before the next activate is required. We cannot use the 
losing side of the focus callback since the callback is being absorbed. The 
code to restore the callback cannot be part of the applicationActivated: 
method, since we must make sure this method returns before another send 
to it occurs. If only we could delay the callback restore until after we return 
from the method. Actually, we can, by using an instance of Delay. The code 
used in this method delays a few milliseconds before calling the method to 
resetActivate (restore in the callbacks). For each application, we have de¬ 
fined the need to capture the focus callback, to remove this callback so that 
additional callbacks are ignored until we are ready for them, and to restore 
the callback when we are done. 

Another Synchronization Issue 

Now let’s turn our attention to the second synchronization method, 
applicationclosing: , which is called by an application when it is ready to 
shut down. This method will more than likely be called as a result of 
XmNCloseCallback, which is supported by the shell. When the applica¬ 
tion detects the callback, it will clean up and then send the 
applicationclosing: message. The applicationclosing: method does two 
things: it make sure all group applications close down, sending each 
group application the message close; and it removes all dependency and 
keywords. By combining these actions in one method, we avoid multiple 
calls to do one task. 

We could have had the method send the message destroyWidget to 
each application’s shell, but we decided that a separate method, close , 
allows greater flexibility, giving the application the ability to decide when 
and how it wants to close. The method that performs all of this is: 
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applicationclosing: anApp 

"an application anApp has closed, close all others 
and delete all keywords and dependencies" 

(applications reject: [:a | a = anApp]) 
do: [:a| a close]. 

applications keysDo: [:a | self removeApplicationType: a ]. 

With the controller finally in pretty good shape, we can turn our at¬ 
tention back to the applications we set out to build. 

Designing an Event Framework 

First we need to create an event framework for the applications. Our 
framework consists of the messages each application expects to send 
and receive for a given self-defined event. Let’s think this through a bit 
while recalling the original goals of the SimplePIM application. 

The Calendar application expects to be informed when a new appoint¬ 
ment has been added, and the appointment will be eagerly awaiting the 
notification of date changes. Let’s call the former method newAppointment 
and the latter dateChanged:. The first method will not need to pass an ar¬ 
gument, but what would a date change be without a date? The notifier will 
use one of the Object broadcast methods described in a previous section to 
send its message and our argument. The notifier will be required to re¬ 
spond to the appropriate message by creating the required method. 

Inter-Application Information Passing 

Next on the framework agenda is the method we will use to request and 
obtain data. As you’ll recall, we will pass this message via the Applica¬ 
tion Controller through the use of the request:from: set of methods. 

Once again, checking our list of goals, we find the Calendar applica¬ 
tion is concerned about obtaining the appointments for a given month, 
while the Appointment application is insistent on knowing given dates 
and holiday description, if any. We can tell from this description that 
both methods will require arguments passed to them. As a result, the 
request:from:with: form of the request methods will be used by both ap¬ 
plications when making these requests. Let’s call one method 
appointmentslnMonth: and have it expect a date argument. It will re¬ 
turn a collection, empty or containing all the requested appointments. 
The other method will be called holidayDescription: and will also expect 
a date. It will answer either an empty string or a description string. 
Notice how we avoided nil as an answer. 
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Adding the Update Framework to the Windows 

To start with our modifications, let’s focus on the open method for 
each application. Add this code just below the line “shellmanageChild” 
of each application’s open method: 

shell 

addCal1 back: XmNwindowCloseCallback 
receiver: self 

selector: #closeWindow:clientData:callData: 
clientData: nil. 

This code defines the close callback for each application’s shell wid¬ 
get. Note that we do not set the focus callback, since, as you may recall, 
this is done by the ApplicationController startApplications method. Next, 
we should acid the required closeWindow:clientData:callback selector to 
each application. The selector will be the same for both applications; it 
looks like this: 

closeWindow: a Shell clientData: clientData cal 1 Data: cal 1 Data 
"Process the window close callback." 


| answer | 
answer : = 

(CwMessagePrompter for: a She 11) 

messagestring: 'Quit the Application ?'; 
iconType: XmlCONQUESTION; 
buttonType: XmYESNO; 
prompt. 

answer 

ifTrue: [self saveEntry. 

ac applicationclosing: self], 
call Data doit: answer 

Oops! We lied. Actually, the Calendar application method should not 
have the call to saveEntry. Please remove it before saving the method. 
You may recognize the applicationclosing: method defined earlier. We 
will assign the ApplicationController instance to the instance variable 
ac in the controller: method we will soon be defining for each applica¬ 
tion. A prompter is used to verify that the user wants to quit. 

Let’s continue defining methods shared by both classes. Look at the 
code for the close method: 



BM SMALLTALK 


232 


cl ose 

"I've been told to close 
so do any clean up stuff" 
self saveEntry. 
shell destroyWidget. 

Again, the CalendarWindow method of this name is the same, except 
for the unneeded call to saveEntry. Now for the controller: method prom¬ 
ised above: 

controller: an Application Controller 
"Set my ac to anApplicationControl1er" 
ac := anApplicationControl 1 er 

This time the code is identical for both applications. 

Finally, we need the two methods that implement the activate event 
structure. Again, the code is identical for both windows. Both methods 
are presented here: 

activated: aShell clientData: clientData callData: cal 1 Data 
"Process the window focus callback." 

| answer | 

callData reason = XmCRLOSINGFOCUS ifTrue: [ A self]. 
self removeActivate. ac applicationActivated: self. 

activate 

"I need to activate so disable 
my focus callback then bring my 
shell to front" 
self removeActivate. 
shell bringToFront. 

Both of these methods call an undefined remove Activate, which we 
will get to in a moment. 

Notice the use of the constant XmCRLOSINGFOCUS in the first method. 
This is a constant in the CwConstants pool variable. Although there is 
only one callback for both gaining and losing focus, the callData struc¬ 
ture returns a reason the focus callback occurred. The constant 
XmCRLOSINGFOCUS indicates the reason the callback was losing focus, 
and XmCRFOCUS is used for gaining focus. Being able to differentiate be¬ 
tween callbacks gives us the ability to ignore one and execute on the other. 
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As we stated earlier, when the windows have settled down after being 
brought to the front, we want to turn the focus callback on again. This 
method accomplishes that task: 

resetActivate 

"set enableActivate to true 

so I can once again respond to focus 

callback" 

shell 

addCal1 back: XmNfocusCal1 back 
receiver: self 

selector: #activated:clientData:call Data : 
clientData : nil. 

And finally, we can get back to the method used earlier, remove Activate, 
which uses the opposite code to remove the callback. 

Adding the Event Messages 

We have two methods to create, one for each of our applications classes. 
We have already discussed and designed the methods, so now all we need 
to do is write them. We will start with the newAppointment notification that 
is broadcast from the AppointmentBookWindow class and defined in each 
dependent’s class. The CalendarWindow instance method is: 

newAppointment 

"Event handler " 
self h ; ghlightCalendar. 

We make a mental note to add the code to show appointments after 
we define the required request method. 

The second method is the CalendarWindow broadcast message for 
notifying dependents of a date change. The method needs to be defined 
in the dependent application’s class. Here is the ApplicationWindow in¬ 
stance method: 

dateChanged: aDate 

"calendar date has changed notify apptBook and 
update display" 

I appts | 

self saveEntry. "Make sure entry is saved" 
appts := apptBook scheduleFor: aDate. 
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self displayHolidayDescription: 

(ac request: #hol i dayDescri pti on : from: //calendar with: aDate). 
self set Label. 

A self setSchedule: appts. 

Notice the request being made on the third and fourth lines of the 
method. We will be defining the method itself in the next section. So that 
our list of mental notes doesn’t get too long, let’s dispose of the setLabel 
method with no further delay: 

setLabel 

"display currentDate label" 

shell title: apptBook weekdayMonthDayYearString. 

The only thing that remains to be done in this section is to modify the 
methods that make the broadcasts. 

For the CalendarWindow class, these would include the method 
dateSelected :, which is displayed below with code changes in bold: 

dateSelected: aString 

"aDate was selected update calendar and 
myself" 

| label | 

aString = ' ' ifTrue: [ A se1f]. 
calendar day: aString asNumber. 
selection notNil ifTrue: [ 

self highlight: selection withBackColor: CgRGBColor white], 
self broadcast: #dateChanged : with: calendar date, 
selection := aString. 
self highlightCalendar. 

The Appointment requires two methods to be modified. Both were 
defined as templates but so far have no code. They are new:clientData:- 
callData: and delete: clientData-.callData :. 

Here is the code for the first method, which will notify its dependents 
when a new appointment has been created by the user. 

new: widget clientData: ignore callData: data 
"user wants to add an appt, prompt for 
startTime and endTime" 

| appts startTime endTime | 
startTime := CwTextPrompter new 
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title: 'New Appointment'; 

messagestring: 'Enter the Appointment Start Time: '; 
answerstring: '08:30 AM'; 
prompt. 

startTime isNil ifTrue: [ A nil]. 
endTime := CwTextPrompter new 

title: 'New Appointment'; 

messagestring: 'Enter the Appointment End Time: '; 
answerStri ng : '10:30 AM'; 
prompt. 

endTime isNil ifTrue: [ A nil]. 

appts := apptBook start: startTime end: endTime entry: 

String new. 

self broadcast: #newAppointment. 
self setSchedule: appts. 

Note that we use two text prompters, one after the other, to get the 
start and end times of the new appointment. If either prompter is can¬ 
celed, the whole process is aborted. After the appointment has been 
created and its elements set, the method performs the broadcast, and 
last of all, it updates the schedule list. 

The next method uses the newAppointment notification to indicate that a 
change has occurred in the status of appointments. Here is the method: 

delete: widget clientData: ignore cal 1 Data: data 
"user wants to delete current appt, delete it 
after prompting for verification. Update schedule list" 

I appts | 

((CwMessagePrompter for: shell) 

messagestring: 'Delete Current Appointment ?'; 
iconType: XmlCONWARNING; 
buttonType: XmYESNO; 
prompt) ifFalse: [ A se1f]. 
appts := apptBook deleteAppointment. 
self broadcast: #newAppointment. 
self setSchedule: appts. 

The deletion is verified, the appointment is deleted, the broadcast is 
performed, and finally, once again, the list is updated. In the next sec¬ 
tion we will work with the information request side of the 
ApplicationController framework. 
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Adding the Request Messages 

We have finally come to the information retrieval methods and the end 
of the framework assignments. In a very short time we will have a test¬ 
able application. But first (there always seems to be a “but”), we need to 
create a few more methods. Once more we will be working in both of the 
application classes. Let’s start with the CalendarWindow class instance 
method holiday Description:, which takes a Date for an argument: 

hoiidayDescription: aDate 

"answer the holiday description for aDate" 

A calendar hoiidayDescription: aDate. 

Next is the appointmentsInMonth: instance method in class 
AppointmentWindow, which also takes a Date for an argument: 

appointmentsInMonth: aDate 

"answer the appts for the month in aDate. 

Request handler" 
apptBook notNij 

ifTrue: [ A apptBook appointmentsInMonth: aDate] 
ifFalse: [ A OrderedCol1ection new]. 

As you can see, the method meets all our requirements, answering a 
collection, either empty or full of appointments. 

Modifying the methods that will make these requests will be our next 
task. We will again start with the CalendarWindow class. The method 
that needs to know about appointments is the one responsible for show¬ 
ing them, highlightCalendar , a previously modified method. Here is the 
final method (changes are in bold): 

high!ightCa]enda r 

"highlight the appropriate dates in the calendar" 

| today holidays appts| 
holidays := calendar showHolidays . 

holidays do: [:h | self highlight: h dayOfMonth with: CgRGBColor 
red] . 

appts := ac request: #appointmentsInMonth: from: #AppointmentBook 
with: caiendar date. 

appts do: [:a | seif highlight: a dayOfMonth with: CgRGBColor 
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blue]. 

selection not Nil ifTrue: [ 

self highlight: selection withBackCol or: CgRGBColor gray], 
calendar showToday 

ifTrue: [ today := calendar today. 

self highlight: today dayOfMonth with: CgRGBColor 
green. 

(weekdays children at: today daylndex) foregroundColor: 
CgRGBColor green. 

]. 

We have, of course, already made the changes to the ApplicationBook- 
Wimdow ins tance method dateChanged:. This means we are done with 
the framework. In the next section we review what we have done. 


Summarizing the Message Framework 

We have now built a message framework that permits inter-window and 
application messaging to occur. Using this framework, we have built our 
event handling mechanism and gained greater control over the func¬ 
tioning of the independent windows. We have also provided a means by 
which applications can request information from one another. To this 
point our framework looks like this: 


SENT BY 


NOTIFICATION OF 


dateChanged: aDate 

newAppointmem 

Request 

holidayDescription: aDate 
appointmentlnMonth: aDate 
Sync Events 

applicationclosing: anApp 
applicationActivated: anApp 
active 


CalendarWindow 
AppointmentBookWindow 
Sent To 

CalendarWindow 
AppointmentBookWindow 
Sent To 

ApplicationController 

ApplicationController 


Calendar date change 
Appt added or deleted 
Answer 

Empty string or description 
Empty collection or appts 
Notification Of 
User quits application 
Window of application 


Setting the Holiday Descriptions 

Now that the inter-application communication structure has been com¬ 
pleted, let’s go back and make sure we have all the methods necessary 
to fill in the structure. One method we referenced as we were describing 
the infrastructure was displayHolidayDescription:. 

We saw this method in the AppointmentBookWindow event handler 
method dateChanged:. Recall that there is a lot going on in this method. 
Not only does it handle an event, it is also the method that makes the 
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holiday description request. The answer from this request is assigned to 
the holiday label through the method display HolidayDescription:, which 
is defined as: 

displayHolidayDescription: aString 

"display entry in text and set labels" 
holiday labelstring: aString. 


Returning to the Menu Callback Methods 

While defining the widget tree early in this chapter, we defined the method 
for creating the menu bar and the Edit and Appointment menus, but we 
created only template methods for each menu item’s callback method. 
We can now go back to fill in the code for each of these methods. 

We will begin with the Edit menu, which needs to process cutting, 
copying, and pasting of text. IBM Smalltalk makes this task quite easy, 
since all we have to do is call some predefined text widget methods. 
Here, then, is the code for processing a text selection cut: 

cutText: widget clientData: ignore callData: data 
"Cut user's text selection to 
the clipboard" 
text cutSelection. 

The other Edit menu handler methods are just as complicated. Their 
code is: 

copyText: widget clientData: ignore callData: data 
"Copy user's text selection to 
the clipboard" 
text copySelection. 

pasteText: widget clientData: ignore callData: data 
"Paste clipboard selection to 
the text entry" 
text paste. 


Even easier are the Appointment menu callback methods. Since we 
already finished the methods for the New and Delete menu items, we 
have only one method left to define, and that is save. The save method 
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processes a user request to save the current appointment on demand, 
which is provided just in case the user doesn’t trust our automated sav¬ 
ing feature. The method simply calls the same method the automated 
facilities do, saveEntry. Here is the code: 

save: widget clientData: ignore callData: data 
"user wants to add an appt 
self saveEntry. 


Adding Holiday Entries 

As you’ll recall, we want to let the user enter holidays into the calendar. 
We’re storing holidays in a Dictionary where the date is the key and the 
associated entry is a string describing the holiday. The method 
enterHoliday will be a CalendarWindow instance method. We will need 
two items from the user: the date of the holiday and its description. We 
can base this method on the AppointmentBookWindow instance method 
new:clientData:callData:, which uses two prompters to get the start and 
end times of a new appointment. Here is the modified and renamed method: 

enterHoliday 

"Menu handler; prompts for string, adds result to holiday 
dictionary" 

| answer answerDescription date | 
answer := CwTextPrompter new 
title: 'New Appointment'; 

messagestring: 'Enter the date of the Holiday to add: '; 
answerString: ' 1/1/95 ' ; 
prompt. 

answer isNil ifTrue: [ A nil]. 
answerDescription := CwTextPrompter new 
title: 'New Appointment'; 

messagestring: 'Enter the description of this holiday:'; 
answerString: 'New Year'; 
prompt. 

answerDescription isNil ifTrue: [ A nil]. 

Calendar addHolidayFromStri ng : answer named: answerDescription. 
self highlightCalendar.. 

Once again, borrowing code saves the day. We need some way for the 
user to indicate a desire to enter a holiday, so we’ll add a button to the 
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CalendarWindow addMenuBar: method. All we have to do is copy the 
last button, “Refresh,” and change its details for our purposes. We want 
this menu item on the same menu, so we use the same form to create it. 
As a last-minute thought, we should also add a separator between “Re¬ 
fresh” and this new menu item. Since this is a large method, we will 
display only the modified segment of code: 

sep := form createSeparator: 'sep' 
argBlock: [:w | 

w separatorType: XmSINGLELINE]. 
sep manageChild. 

enterHoliday := form 

createPushButton: 'Enter A Holiday' 
argBlock: nil. 

enterHoliday addCallback: XmNactivateCal1 back 
receiver: self 

selector: #enterHoliday:clientData:callData: 
clientData: nil. 
enterHoliday manageChild. 

Don’t forget to add the new temporary variables to the methods vari¬ 
able declaration. The separator bears some explanation, since this is 
the first time we’ve used one. It is created in the same way as a button 
by sending its creation method to the form on which it is to appear. The 
XmSINGLELINE type indicates we want only a single line separator. This 
newly added menu item in turn creates the need for another menu call¬ 
back method enterHoliday:clientData:callDate:, which simply calls the 
enterHoliday method. The code is left to you. 

Topping off the Tank 

One issue that may come up after the user has worked with the applica¬ 
tion a while is the need to return quickly to today’s appointments. Al¬ 
though the user can click on the Today button to do this, it would be 
nicer and require fewer mouse clicks if we added this ability to the Ap¬ 
pointment menu on the AppointmentBookWindow menu bar. Adding a 
menu item is relatively easy. The catch here is how to tell the Calendar- 
Window to switch to today’s date. 
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To the rescue comes our inter-application communication scheme. To 
communicate our need to CalendarWindow, we will use a request mes¬ 
sage. Setting up for this process requires us to add methods to each 
application involved in the communication. 

On the AppointmentBookWindow side, we need a method to start the 
process, which itself will be started by a new menu item callback method. 
That’s two new methods and a modification to the addMenuBar: method. 

On the CalendarWindow side, we need only one method that will ac¬ 
cept the request and act on it. Okay, let’s do it, starting with the 
CalendarWindow. The new today method is defined as: 

today 

"request has been made to switch to today, 
answer the todays date" 

self today: nil clientData: nil callData: nil. 

A calerdar date. 

Here is a twist: We are calling a button callback from another method. 
Since the method ignores all the data passed to it, we can pass it nil 
values. Using this scheme allows us to have the request act exactly the 
same as the button press would. We answer today’s date. 

The AppointmentBookWindow changes require us to modify the 
menu—we will get to these changes in a moment—and add two new 
methods: one method for processing the request and one to handle the 
menu callback. We can actually combine these functions in the same 
method. Without further ado, here is the method: 

today: widget clientData: ignore callData: data 
"User wants to look 
at today’s appts" 

| date | 

date := ac request: #today from: #calendar. 
self dateChanged: date. 

The menu change is next. Once again, copy the last menu button in 
the addMenuBar: method and change its details. Here is the modified code: 

item := form2 

createPushButton: 'Today' 
a r g B1o c k: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 
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selector: //today: cl i entData : call Da ta : 
c1ie n t D a t a: nil. 
item man ageChi 1d. 

We want the menu item on the Appointment menu, so we create it 
with form2. We used the already defined temporary variable, item, so 
this time we don’t have to change the method’s declaration. Before we 
run a test, let’s make one final change to synchronize the appointment 
book with the calendar at start-up. We can do this by having the 
AppointmentBookWindow setUp method point to our new today:client- 
DataxallData: method. Again, we set the arguments to nil Here is the 
last method: 

setup 

"setup apptBook" 

apptBook := AppointmentBook new. 

self today: nil clientData: nil cal 1 Data: nil. 

Testing the Application 

It’s been a bit of a long haul, but our hard work is about to pay off. 
Starting the application is a little different, since we can now use the 
Application Controller to start all the applications at once. Here is the 
code to turn the key and start the engines roaring: 

Appl!cationController launch. 


If you haven't been following along and entering the code from the book, and if you 
opted earlier to load the SMPIEPIM.APP file, have we got a surprise for you! The 
^ SPSfVIBUG.APP file has the bug fix removed, so you can follow along with this 

section. 


Run the application through the set of tests discussed in Chapter 7. 
Test the intercommunication framework by adding some holidays and 
seeing if the descriptions show up in the appointment book. 

The first thing you will probably notice is that the multiple dates are 
selected in the calendar when you change months or years. This is quite 
unsightly. We will have to fix this immediately. 




CHAPTER 9: AN APPOINTMENT BOOK 


243 


Handling the Highlight Mess 

What could be causing this problem? We’ve already added code to change 
the selection back to white when a new selection is made. Is that fix not 
working? Click on the extra highlights and then click elsewhere. The 
highlight is removed, so the selection code appears to be working. What 
is the problem here? Let’s think about the flow of the application high¬ 
lighting process a little. Dates are highlighted by the highlightCalendar 
method, which sets the color of special dates. The only highlight not 
handled there is selection highlight. When we navigate through the cal¬ 
endar, the colors for these dates are removed. Who does this? Of course, 
updateCalendar. Remember, the last thing the loop does is to set the 
color of each button back to black. 

That’s all that is wrong. We just forgot to set back highlighted dates to 
white when the calendar is changed. All we need to do is add code to the 
end of the loop that sets the background color of each label widget to 
white. Here is the code segment with the change in bold: 

1 to: 42 do: [: i | 

aButton := dates children at: i. 

((i - startX end and: [i >start]) 
ifTrue: [ 

aButton labelstring: ( i -start) printstring. 

] 

ifFalse: [ 

aButton labelstring: ' ']. 

aButton foregroundColor: CgRGBColor black. 

aButton backgroundColor: CgRGBColor white]. 

Another Test 

We are ready for another test. One more time, run the application through 
the set of tests we discussed in Chapter 7, this time adding some ap¬ 
pointments to various days to make sure the appointment book displays 
and updates its contents as expected. 

At some point you’ll notice that appointments are not being preserved 
as you switch dates. Try to figure out what’s happening. (Hint: The prob¬ 
lem also occurs when adding new appointments.) We’ll describe the 
source of the problem in more detail in the next section and propose a 
solution in the section after that. 
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Finding the Source of the Problem 

Let’s first try to determine the scope of the bug: Is it in the save or re¬ 
trieval side of scheduling? How can we determine this? We could look 
directly at the Appointments class variable, but there is another way. If 
they are properly saved, appointments should cause their day to turn 
blue in the calendar. Pick a date on a month other than today’s month. 
Type a string into the appointment book window. Now move to the next 
month, then back again. Interestingly enough, the date is blue. So the 
dates are being saved. 

Next, let’s see if schedule is saved. Click on a blue date and notice that 
the schedule list is refreshed with the assigned appointment start times, 
and none seem to be missing. Also note that not all dates are blue, so we 
are properly distinguishing between scheduled and nonscheduled dates. 

Well, now that we know schedule is saved, we can ask if the correct 
string is stored with each appointment. We will look at the class variable 
to verify this. Here is where the printOn: method we created earlier will 
help a lot. 


You did add this method, didn't you? We made it optional at the time, but it is 
essential now. in case you didn't add it, here is the Appointment instance method 
^ again: 

printOn: aStream 

"display object information" 

aStream nextPutAIS: start printstring/:',entry. 

The entry will appear at the end of each string. We use so we can recognize the 
object but get more into each view. 


Inspector Gadget to the Rescue 

Open an inspector on the class variable Appointments. Now select a non¬ 
blue date and add an appointment to it. Now check on the entry in the 
inspector by clicking on “self’ in the inspector and scanning the text for 
the entry. To see a list of keys, choose Inspect from the inspector’s Vari¬ 
ables menu. A new inspector opens all the keys listed, including the newly 
added date. (Note that you must reopen the inspector to see new keys.) 
Each entry in the list will have a SortedCollection associated with it. To 
view a list of the elements of this object, inspect it. Finally, to view the 
appointment itself, click on it and inspect it. 
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If you feel you have too many inspector windows open, then you should 
appreciate the printOn : code. This reveals the contents of each appoint¬ 
ment instance without necessitating the opening of a successive level of 
inspectors. At each level, when an appointment is displayed, it looks like 
“@08:30 AM: ‘Mtg.’” 


The easiest way to inspect a class variable, and one that does not require you to 
type code, is to use the TraiSBSazer to select a method where the variable is used, 
select the variabl e name, and inspect it. To do this, select a class and then use the 
Class Variables combobox selection in the Instance Method list to search for 
methods using the class variable. To make things even easier on yourself, once you 
are inspecting the appointments, use the Inspector's Variables menu Remove Key 
menu option to eliminate all but a couple of dates. 



Let’s continue our debugging by making an entry for the appointment 
and clicking on a non-blue date. The entry should be saved automati¬ 
cally. Is it? Yes, so we know the problem isn’t with automated saving. 
Click on another date and look in the inspector. What’s this? The entry 
we just saw a moment ago is gone. The appointment is there, but the 
entry is gone. 

Vanishing Entries 

How bizarre! Entries that vanish after being verified. Retry the test a 
few times. Every third click, the entry disappears. What happens if we 
select a date with an appointment as our selection? 

Click on an appointment date, add an entry, click on another appoint¬ 
ment date, and check the inspector. Now, click on an appointment and 
check the inspector. The entry is gone. So it isn’t the date selection but 
the appointment selection that causes the entry to vanish. 

Try this same process again, but this time for the entry of an appoint¬ 
ment use the appointment’s date; for instance, use an entry of 12/20/94 
for the appointment on December 20, 1994. Wow, what do you know? 
The entry is being assigned to the wrong date. Now we have something 
to work with. 
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Bringing in Some Hailing Help 

It’s time to extend our debugging process and bring in some more help. 
No, not your neighbors. Well, not unless they plan to buy this book. We 
are referring to the debugger. Let’s add a halt to the method that selects 
appointments, appointments elected: clientDate:callData:. With both the 
inspector and a debugger we should be able to get to the root of this 
problem. At the top of this method, add the following code: 

self halt 

Save the method and click on an appointment date. Select an appoint¬ 
ment. “Resume” the debugger and add an entry to this appointment. 
Click on any other appointment date. Now check the inspector. The en¬ 
try is still there. 

The first thing to do is to try to determine which line of code in this 
method is causing the problem. We will do this by checking the inspector 
after executing each line. When the inspector shows the entry has gone, 
we have our line. Click on an appointment. The debugger will come up. 
This time we want to run the code, so find the appointmentSelected: 
method in the list and click the Over button twice. The inspector shows 
that the appointment entry is gone. So the saveEntry method is the cul¬ 
prit. Resume the debugger and set up for another run. 

With the debugger once again open, hit the Over button and then Into. 
Once more, click Over and then Into. This will take us into the saveEntry 
method. We can now inspect the variables used in the method. Look at 
aString and see what it contains. It appears to be empty. From here we 
can also inspect the AppointmentBook instance. Double-click on “self’ 
in the middle column. This brings up an inspector. Click on currentAppt. 
Notice that it has an entry with the date we just entered. Look at the 
Appointment Book’s label; it displays the currently selected date. Has 
the appointment already been changed? A quick check of the Appoint¬ 
ments Dictionary inspector tells us no, the appointment is okay. Click the 
Over button twice. Now check both inspectors. The entry is gone. 

We just assigned the entry from the selected date to the entry of the 
previous date. That explains why the label seemed to jump from date to 
date. Clicking the Over button enough times brings you back to the method 
with the halt. So the damage has been done. 

It looks like the currentAppt instance variable is not being updated 
when a selection is made. Who is responsible for assigning currentAppt .? 
The quickest way to tell is to set the Instance Method list to Instance 
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Variables. Clicking on the currentAppt variable displays a list of the 
methods that make reference to it. Clicking down the list displays the 
source code for each method. Quite handy, isn’t it? 

The method that is executed next in the appointments elected: method 
is appointmentStarting: . This method sets currentAppt to nil before re¬ 
setting it to the detected method. The damage, however, is done before 
we reach here. We also know the problem occurs only when we select 
dates, not when we select another appointment from the list. We don’t 
need to delve into this method any further. Or do we? 

Rethinking the Results 

Think a bit about how the method works. It detects an appointment with 
a given start time in the current schedule. The keyword here is current. 
What if we have been barking up the wrong tree, or in this case, collec¬ 
tion? All our efforts have focused on the Appointments Dictionary. Per¬ 
haps we should have been looking instead at the schedule. 

Let’s put a halt in the appointmentStarting: method. Be sure to re¬ 
move the one from the appointments elected: method. 


A quick way to place this halt is to choose Open Messages from the Image menu and 
enter "halt" into the resulting dialog. A new browser will be brought up, with only 
the halt method iim the list. Select All Senders instead of the default ASS Implementors 
and click on the desired method. Remove the offending line of code, save the 
method, and close the browser. 



Set up as before, only this time make sure your appointment dates 
each have an appointment with a different start time. This setup will 
permit us to more easily identify the schedule of appointments with which 
we are dealing. 

When the debugger opens, inspect self and look at the variables sched¬ 
ule and currentAppt. The appointment in currentAppt is not in the sched¬ 
ule. They are out of synch. 
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Solving the Problem 

What do we do to fix this problem? We need to make sure the currentAppt 
variable is tracking an appointment in the current schedule. This means 
that when the schedule is updated, the current appointment should be 
updated as well. What should the current appointment be updated to? 
Since we are in an unknown state, the best thing is to set it to nil 
Now where do we implement the fix? We should add this to the method 
that updates the schedule. We can determine this by looking at the meth¬ 
ods that reference this variable, as we did earlier with the currentAppt 
variable. We see from the resulting list that three methods have an in¬ 
terest in schedule. These are the methods: 

appointment Starting: 
deleteAppointment 
getCurrentD ay Schedule 

We can eliminate the first method, since we know it already sets currnt- 
Appt to nil The second is an unlikely candidate, leaving the third. Add 
the code to set currentAppt to nil at the top of this method and save it. 

Another Color 

On some systems, the color white is not the right color to use to reset the 
background highlighting used for date selection. As a result, the labels 
appear in different shades of color than the form they are on. To correct 
this problem, use the background color of the rowColumn dates instead. 
Instead of CgRGBColor white, use: 

dates backgroundColor. 

Add this code change to the CalendarWindow dateSelect: method and 
the updateCalendar method. We leave the implementation details to you. 
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Some Things to Ponder 

You should now have a fully functional application that you can custom¬ 
ize to your own liking. In coming chapters we will add even more en¬ 
hancements. In the meantime, you can ponder some things that may 
need changing, or at least we will present them here so you will know 
that we know they are there: 

1. Selecting a date over 29 and navigating into February produces a 
debugger saying “Improper Date.” 

2. The UI of the Appointment Book can be a little confusing when a 
new date is selected. It would be better if a default appointment 
were chosen and displayed instead of the entry area and its labels 
being left empty. 

3. It might be a nice enhancement for the Appointment Book to dis¬ 
play the word “Today,” instead of a holiday description, in the 
Today highlight color for today’s appointments. 




C H A P T E R 


The Graphic World 


Smalltalk’s wholly graphic environment sets it apart from most other 
programming languages. It is no surprise that we can control its graphic 
nature and create interesting and useful graphic patterns. In this chap¬ 
ter we’ll examine the graphic world of IBM Smalltalk in depth. We’ll 
look at IBM Smalltalk’s implementation of basic concepts of graphic pro¬ 
gramming. Then we’ll examine the use of forms and drawing primitives 
in the language, pausing to look at the basic mathematics involved in 
calculating and drawing graphic objects. 

We’ll undertake our usual triage of the graphic classes, focusing on 
classes and methods that are important for adding graphics to Smalltalk 
applications. This will prepare us for Chapter 11, where we will design 
and construeI; a highly graphic application. 

Following Along 

The file chaplO.wsp in the Chapter 10 folder has been provided to help you 
follow this discussion. It contains all of the sample code for this chapter. 



Everything displayed on the IBM Smalltalk screen (windows, lines, cur¬ 
sors, and even text characters) is composed of a series of dots arranged 
in a pattern. These dots are called pixels , short for “picture elements.” A 
line is formed from a continuous vector of such dots whose color is black 
(on a monochrome display) or any color contrasting with the background 
(on a color display). 

Like the windows, IBM Smalltalk graphics rely heavily on the X Win¬ 
dows System. IBM Smalltalk has gathered all graphics classes under the 
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core Common Graphics application. Common Graphics classes are pre¬ 
fixed with the letters “Cg,” as in CgRGBColor or CgGC. With the excep¬ 
tion of the Common Graphics Image Support classes, the Common 
Graphics classes are founded in the X-Windows system’s library of graph¬ 
ics operations (Xlib) and provide all the same functions as the Xlib C 
calls. (Those of you familiar with the Xlib graphics operations should 
check out the IBM Smalltalk Programmer’s Reference for a description 
of the Xlib calls that were converted to Smalltalk classes and methods.) 

The most important Common Graphics classes are: 

CgDisplay 

CgDrawable 

CgGC 

CgGCValues 

CgPixmap 

CgWindow 

CgScreen 

CgRGBColor 

The ability to draw and display graphics on your computer display is 
under the control of CgDrawable, which represents a window or bitmap 
(in IBM parlance, a pixmap), and CgGC, which represents a graphics 
context. All drawing operations are performed on a CgDrawable by a 
CgGC. When drawing in a window, the CgDrawable represents a 
CgWindow, which is itself a link to a Common Widget object instance. 
Widgets cannot be drawn on directly but have a corresponding window, 
a CgWindow, which can be used for drawing. A widget’s window can be 
accessed by sending the window message to a widget. 

The actual drawing is performed by sending a message to a window 
with the CgGC (also known as a GC) as an argument. For example, to 
draw a point, you send the window the message drawPoint: aGC x:10 
y:20. To try this you need to access a window and GC. Fortunately, IBM 
Smalltalk makes this easy by providing defaults for each of these objects. To 
draw a point, type the following on your screen (the top-left corner of 
your desktop must be clear of any windows to see these examples): 

CgWindow default 

drawPoint: CgGC default 
x: 10. 
y: 20. 
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A single point may be difficult to see, so try this code segment to dis¬ 
play a line: 

CgWindow default 

drawPoint: CgGC default 
xl: 10. 
yl: 20 
x2: 50 
y: 2 50. 

As you can see, the class method default answers the default for each 
object. In this case the default is the screen and its window, so the line is 
drawn on the background of your desktop. 


Accessing the Graphics Subsystem Constants 

The pool dictionary CgConstants provides access to constant values that 
are used in the graphics subsystem. The constants are particularly use¬ 
ful when getting and setting GC attributes. The dictionary contains names 
for all of the GC attributes which may be used in conjunction with meth¬ 
ods for setting and getting groups of attributes. The class definition of 
any object you create that uses the Common Graphics subsystem should 
include CgConstants as one of its pool dictionaries. 

The Graphics Model 

The relationship among these seemingly disparate components as they 
work together in the graphical world of IBM Smalltalk becomes clearer 
when viewed in the context of the rest of the supporting classes in the 
model. The following figure represents the graphics model hierarchy 
from graphics server to physical display to drawing surface. 

Let’s look at the individual classes which form the graphics model. 


CgDSsp!ay r the Link to Your Application 

Before you can understand the CgDisplay class, you have to remember 
that the X-Windows system is a client/server environment. This means 
that all graphics operations are actually performed on the client by the 
graphics server. The CgDisplay represents the link among your applica- 
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tion, the client, and the graphics server. An application can actually be 
linked to multiple graphics servers (although in most cases you use only 
one, the default) and therefore, multiple display objects. 


CgScreen, the Physical Display 

A CgDisplay communicates to a CgScreen object, which itself repre¬ 
sents a single hardware output device, such as a Super VGA graphics 
adapter and monitor. The object contains information about the device, 
including its dimensions, color capacity, and a default graphic context 
(GC), such as 640 x 480 by 256 colors. The default screen is the desktop 
and can be accessed with the class message default , or the CgDisplay 
class method defaultscreen. 


CgDrawabie, What to Draw On 

A CgDrawabie is an area that can be drawn on. All drawing operations 
are performed on a drawable, which can be either a CgWindow or 
CgPixmap, both of which are CgDrawabie subclasses. Considering the 
client/server approach of X Windows, you can think of the drawable as 
the place that the graphics server draws the operations requested by 
the application. All drawing operations are performed with respect to 
the origin (the point 0@0), which is the upper-left corner of the draw- 
able. In our example above we drew a line from the upper-left corner 
towards the bottom-right corner. This class defines most of the drawing 
methods, including those for points, lines, rectangles, and polygons. 

CgWindow, the Link to Widgets 

As we explained earlier, each widget contains a window object. It is the 
window object—a CgDrawabie subclass, CgWindow—that is the visible 
portion of a widget. Everything you see in IBM Smalltalk is displayed 
within a window. The default window is the desktop window. To display 
graphics within a widget you must first access the widget’s window in¬ 
stance by sending the message to the widget. A CwDrawingArea widget 
provides a freeform drawing area. 
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GgPIxmap, Bitmap Images 

A subclass of CgDrawabie, the CgPixmap instance represents an off¬ 
screen monochrome or color bitmapped image. A bitmap is an array of 
pixels which represent an image. The more colors a pixmap contains, 
the larger the number of bits required to represent each pixel, resulting 
in a larger amount of space required to store and display the pixmap. 
For this reason, pixmap storage tends to be device-dependent and pixmap 
memory is not directly addressable from your application. A pixmap is 
often used to cache the results of drawing operations for high-speed 
display. To display a pixmap, simply copy a rectangular area of its con¬ 
tents to a window. The creation, manipulation, and freeing of pixmaps is 
left as a responsibility for your application. 


CgGC, the Graphics Context 

The CgGC object contains information concerning drawing attributes, 
such as foreground and background colors, line width and style, fill style, 
and font. When an object is drawn on a CgDrawabie instance, the draw- 
able interacts with the GC to determine how the object should appear. 
When we drew the line earlier, the drawable checked with the GC for 
the foreground color and line width to use. The default GC can be ob¬ 
tained by sending the message default to the CgGC class or sending an 
instance of the class CgScreen the message defaultGC. 


CgGCValues, Saving Time and Attributes 

Associated with CgCG is CgGCValues. This object is provided for the 
sake of convenience, providing a value storage place without the over¬ 
head of a GC. Instead of having to set the attributes of several CgGC 
objects, you can set a single CgGCValues instance, then pass these val¬ 
ues on to each GC. 



256 


IBM SMALLTALK 


The Classes CfGC and CgGCValnes 

The classes CgGC and CgGCValnes are so critical to drawing graphics 
that we will focus our attention on them before moving on to perform 
some simple drawing operations. You are responsible for creating, set¬ 
ting, and freeing a GC. Convenience methods have been provided for 
each of these tasks. 


Working with GCs 

The key to working with GCs is handling the GC’s attributes. Each GC 
tracks a series of attributes which controls the color and appearance of 
drawn objects. Most Smalltalk objects provide gel/set methods for their 
individual attributes, but a GC has so many that IBM Smalltalk has pro¬ 
vided methods for working with groups of attributes as well as separate 
classes to contain attributes. 

The easiest way to work with a GC is to use the default GC for the 
window by sending the message defaultGC to a CgScreen instance. How¬ 
ever, you should only use the default GC for experimentation; you must 
create a new GC for your application. 

The easy way to create a GC is to send a CgDrawable the message 
createGC: values using the parameters none and nil. For example: 

I | 

gc := CgWindow default 
createGC: None 
values: nil. 

This results in a CgGC instance set to all default values. The method 
takes two arguments. The first argument of this method is a values mask 
set to the attributes you want to set and the second argument is the 
values of the attributes masked, usually a CgGCValnes instance. 

The mask, whose format admittedly looks more like C then IBM 
Smalltalk, is used to mask the attributes you want to modify in the 
CgGCValnes instance passed as the second argument. The mask is written 
by ORing together the values you want to set (i.e., GCForeground I 
GCLineWidth). (The IBM Smalltalk Programmer’s Reference includes a list 
of the attributes and default values.) The names for the attributes are taken 
from the CgConstants pool dictionary described above. Set the mask to None 
and the value to nil to create a new GC with all default values. 
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If you want a new CgGC instance that does not use all default at¬ 
tributes, set the modified attributes in a new GCValues object and create 
the GC using the values object. The following code segment creates a GC 
with modified line width and style attributes: 

j gc gcValues | 
gcValues := CgGCValues new 
1 i n e W i d t h : 2 ; 
lineStyle: LineOnOffDash. 
gc := CgWindow default 

createGC: GCLineWidth | GCLineStyle 
values: gcValues. 

Another way to do the same thing, saving a variable and a few lines of 
code, is: 

I gc I 

gc := CgWindow default 

createGC: GCLineWidth | GCLineStyle 
values: ( CgGCValues new 
1 ineWidth: 2; 

lineStyle: LineOnOffDash). 

Notice that in both examples we are using the default window as the 
drawable. The symbol #LineOnOffDash is also taken from the CgConstants 
pool dictionary. 

To change the values of an existing GC, the message chang eGC-.values: 
is sent the GC. In practice it looks like this: 

I gc I 

"Start with a GC with all Defaults" 
gc := CgWindow default 
createGC: None 
values: nil. 
gc 

changeGC: GCLineWidth | GCLineStyle 
values: 

( CgGCValues new 

1ineWidth: 2; 

lineStyle: LineOnOffDash). 
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To retrieve a value from a GC, send it the message getGCValuesivalues- 
Return:, which uses the mask format as above and looks like this: 

| gc gcValues 1w 1s | 

"Start with a GC with all Defaults" 
gc := CgWindow default 
createGC: None 
values: nil. 
gc 

getGCValues: GCLineWidth | GCLineStyle 
values: ( gcValues : = CgGCValues new ) 

Iw := gcValues lineWidth. 

Is := gcValues lineStyle. 

You can copy GC attribute values to another GC by sending the first 
GC the message copyGC:dest:. This method again uses the attribute mask 
for its first argument but takes the second GC as its second argument. 
Here’s a code segment which continues the last code segment: 

| gc gcValues newGC Iw Is | 

newGC := CgWindow default 
createGC: None 
values: nil. 
gc 

copyGC: GCLineWidth | GCLineStyle 
dest: newGC. 

The final step in dealing with a GC is freeing it. This is a very important 
step because GCs do use resources which must be freed by your applica¬ 
tion before exiting or, better yet, when it finishes with a GC. To free a GC 
send it the message fireeGC. Be sure to free every GC you create. 


CAUTION 


Be sore to use the freeGC message and not free. Free is a private method 
which may have undesired results. Also, do not free the default GC as this 
may have some disastrous results. Our experimentation resulted in errors 
when trying to open new window, including browsers, inspectors, and 
debuggers. 
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Getting Ready for the Demonstrations 

We want to create a window with a CgBrawable so that we can spend 
much of the rest of this chapter demonstrating various graphics opera¬ 
tions. To prepare for these demonstrations, we need two global vari¬ 
ables and some code for creating a simple window. 

To create the global variables simply execute the following: 

Smalltalk at: #Tigger put: nil. 

Smalltalk at: #Nancy put: nil. 

We use these variables to hold instances of CgDrawable and CgGC. 
Execute the following code segment to create a sample window. 

| shell drawingArea drawable values gc| 

shell := CwTopLevelShel 1 

createApplicationShell: 'Example' 
argBlock: nil. 

drawingArea := shell 

createDrawingArea: 'draw' 

argBlock: [:w | w width: 200; height: 200]. 

drawingArea manageChild. 

shel1 realizeWidget. 

values := CgGCValues new 
1ineWidth: 2. 

Tigger := drawable := drawingArea window.. 

Nancy := gc := drawable 

createGC: GCLineWidth 
values : values . 

Your window should look like the one in Figure 10-1. If you close the 
window you must re-execute the above code before proceeding. 
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Figure 10-1. 


A blank Example window 


Demonstrating Basic Drawing 

In this section we do some drawing. We use the CgDrawable instance 
methods to draw lines, rectangles, polygons, and circles. We draw in the 
window we created in the last section using the global variables created 
and assigned to the window’s CgDrawable and CgGC objects. 


Line Basics 

To test our example window, let’s try drawing a line in it. Execute the 
following code: 

Tigger drawLine: Nancy 


xl: 

10 

yl: 

10 

x2: 

100 

y 2 : 

100 


The message is sent to our sample window’s drawable and simply 
defines a line segment. Your window should now look like Figure 10-2. 
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Figure 10-2. 


Example window with drawn line 


To clear the window execute the following code: 

Tigger clearWindow. 

To create a figure using multiple line segments, use the method 
drawLines:points:mode: whose first argument, as it is with all of these 
methods, is the GC. The next parameter requires an array of points. The 
third parameter is a constant, and is either CoordModeOrigin, which 
means that all points should be drawn relative to the origin (0@0, the 
upper-left corner}, or CoordModePrevious, which draws a point relative 
to the previous point. (See Figure 10-3.) We discuss points in detail later 
in this chapter. 

To draw a rectangle we can use the fillRectangle:x:y:width:height: 
method. Here is a code segment that draws this figure: 

Tigger fi11Rectangle: Nancy 
x: 10 
y: 10 

width: 50 
height: 50. 
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Figure 10-3. 


Example window with connecting lines 


Multiple rectangles can be drawn with the fillRectangles.rectangles: 
method, which takes an array of rectangles as its second argument. We 
discuss the Rectangle class later in the chapter. Here is an example of 
this method which draws four rectangles (see Figure 10-4): 

| rects | 

Tigger clearWindow. 

(rects := Array new:4) 

at: 1 put: (Rectangle origin: 10@10 extent: 50@50); 

at: 2 put: (Rectangle origin: 70@10 extent: 50@50); 

at: 3 put: (Rectangle origin: 10@ 70 extent: 50 @ 50); 

at: 4 put: (Rectangle origin: 70 @ 70 extent: 50 @ 50). 

Tigger fi 11 Rectangles: Nancy 

rectangles: rects. 

To draw an unfilled rectangle use the drawRectangle:x:y:width:height: 
method or drawRectangles-.rectangles : for multiple unfilled rectangles. 
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• Foyr rectangles at one time 


Our final example uses the method for drawing a filled polygon, 
fillPolygon:points:shape:mode:. This method takes the same arguments 
as drawLines:points:mode: except that it has added shape parameter. 
The value of the shape parameter is one of three constants, Complex , 
Convex , or Nonconvex. Complex indicates the polygon is either convex 
or self-overlapping. Convex describes a polygon where a straight line 
connecting any two points of the polygon does not cross any edge. 
Nonconvex says the polygon is not convex but also does not overlap. You 
should use Complex , unless you know the shape is Convex or Nonconvex. 
Here is the code for a triangular polygon (see Figure 10-5) : 

| points | 

points := Array with: 10@10 with: 10@60 with: 60@35. 

Tigger fi11 Polygon: Nancy 
points: points 
shape: Convex 
mode: CoordModeOrigin. 

You may be wondering why we don’t need a fourth point to close the 
polygon. Polygons in IBM Smalltalk are automatically closed, so leaving 
the array as: 

points := Array with: 10@10 with: 10@60 with: 60@35 with: 10@10. 


results in the same shape. 
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Figure 10-5. 


A triangle 


You can use the window to try additional drawing methods if you like. 
Be sure to execute the following code before closing the window: 

Nancy freeGC 


Drawing in Color 

So far, we have been experimenting with the default colors. While this is 
fine for examples, few applications today are monochromatic. How do we 
set the foreground and background to something a little more colorful? 


The Class CgRGBColor 

In this section we discuss the class CgRGBColor, which makes it possible 
to work with colors other than black and white. We have already had 
some experience with this class in previous chapters, but now we take a 
look at the class in detail. 

We have been using black and white for our examples. CgDrawable 
has two methods which make setting black and white easy, blackPixel 
and whitePixel. To invert the default black on white foreground and back¬ 
ground colors of a GC, we would use the following code: 
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I gc l 

"Start with e GC with all Defaults" 
gc := CgWindow default 
createGC: None 
values: nil. 
gc 

changeGC: GCForeground | GCBackground 
values: 

( CgGCValues new 

foreground: CgWindow default whitePixel 
background: CgWindow default blackPixel). 

The CgRGBColor class instances specify a color. The color is defined 
as three values representing the intensity of the red, green, and blue 
(RGB for short) primaries. Each value is an integer between 0 and 65535. 

Yon can define a color directly using the class method red:green:blue: 
and indicating the intensities of each color. For example: 

CgRGBColor red:32767 green: 32767 blue: 32767 

This creates a grayscale color object. Alternatively, the method inten¬ 
sities: can be used to specify the same intensity for all three color values. 
For example, the following results in the same color as above: 

CgRGBColor intensity: 32767 

However, unless you know exactly the color you want, setting color in¬ 
tensities can be a bit trying. A better way to create a color is by looking up 
a predefined color name. The CgScreen instance method lookupColor: takes 
an argument of a predefined color name. The color names can be found in 
the file rgb. txt in your IBM Smalltalk directory (assuming you haven’t erased 
it to save space); a subset of the color is in a table which can be found in the 
IBM Smalltalk Programmer’s Reference. Here is an example: 


CgScreen default lookupColor: 'tomato4 
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The Class CgindexedPaEette 

The CgRGBColor cannot be used directly to set a GC’s foreground or 
background color. The GC expects something called a pixel value, which 
is an index into a CglndexedPalette object. An indexed palette is an 
array of colors indexed by a zero-based pixel value. 

The Default Palette 

Palettes are a complex subject area, and our application requirements 
are minimal, so we will restrict our discussion of palettes to the default 
palette. To access the default palette you send the default class message 
to the class CglndexedPalette. The default palette consists of 16 colors, 
indexed from 0 to 15, with 0 defining black and 15 white. One advantage 
of using the default palette is that it does not require additional resource 
allocation. In fact, on most platforms it uses the same colors as the de¬ 
fault color palette supplied by the platform. 

Getting a Color from the Default Palette 

You can access a color within a palette the same way you access an array 
element with the at: method. For example, look at the following code: 

CglndexedPalette default at: 11 

This results in the color yellow on most platforms. An index value 
outside of the palette’s range answers the color black. 

Combining what we already know about the CgRGBColor objects and 
palettes, let’s investigate another CglndexedPalette instance method 
called nearestPixelValue :. This method takes a CgRGBColor object and 
answers the pixel value closest to it in intensity. So to find the color in 
the default palette nearest our sample grayscale color, we would use the 
following code segment: 

CglndexedPalette default nearestPixelValue: (CgRGBColor red: 32767 
green: 32767 blue: 32767 ) . 

To find the color nearest “tomato4,” use the following code: 


CglndexedPalette default nearestPixelValue: (CgScreen default lookupColor 
: 'tomato4 ' ) . 
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Changing the Foreground Color of the Example 
Window 

If you closed the example window you will need to re-execute the above 
code to open a new window before proceeding. 

The following code allows us to modify the foreground color to tomato4: 

Nancy changeGiC: GCForeground 

values: (CgGCValues new 

setForeground: (CglndexedPal ette default nearestPixelVal ue: 

(CgScreen default lookupColor : 'tomato4')). 

An easier way to do this is to use the CgGC convenience method 
setForegroun d: 

Nancy setForeground: (CgIndexedPa 1 ette default nearestPixelVa1ue: 
(CgScreen default lookupColor : 'tomato4')). 

Execute the above code, then try rerunning the multiple-rectangles ex¬ 
ample we did earlier (see Figure 10-6). 
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We now know how to create, set, and use colors. You may want to try 
some other color by using their predefined names in place of tomato4. 
Just be sure you free the GC before closing the window. 

As we stated earlier, palettes are a complex subject area, and there is 
much more to palettes then is covered here. You may want to consult the 
IBM Smalltalk Programmer’s Reference for additional information. 

The Class Point 

We have used quite a few Point objects in previous examples. An in¬ 
stance of the class Point has two important instance variables: x and y. 
As we have said, these represent the horizontal and vertical position of 
the point, respectively. 

To create a new point, send the @ message to an integer. (We saw 
some of this in Chapter 8 when we studied how to define the size and 
relative location of a subpane in a window.) Figure 10-7 depicts a process 
for creating a point and then interrogating it for its coordinates. Notice 
that the point we create is never displayed; we have not given the point 
an instance of class CgDrawable subclass within which to display itself. 


System Transcript 


File Edit Smalltalk tools 


(C) 1994 International Business Machines Corporation. 
All Rights Reserved. 

(C) 1990 - 1 994 Object Technology International Inc. 

VM Timestamp: 1.3, 8/30/94 

15 

35 


Workspace: F:\IBMST\BOOK\CHAP10\CHAP10.WSP 


"Points" 

| aPoint row column | 
aPoint := 15@35. 
row := aPoint x. 
column := aPoint y. 

Transcript cr;show: row printString;cr; show: column printstring. 


jpr 


Figure 10-7. 


Creating and referencing a Point 


CHAPTER 10: THE GRAPHIC WORLD 


269 


We can manipulate instances of the class Point. For example, we can 
add, subtract, or multiply two points or a point and an integer value. If 
you use a point as the argument to any of these messages, then the x 
coordinate of the point used as an argument is applied to the x coordinate 
of the receiver. The y coordinates are treated similarly. For example, 
display the following expressions separately in a Workspace window: 

(15 @ 30 + (-1 @ -2)) x 
((15 @ 30) + (-1 @ -2)) y 

The first expression should return the result 14 and the second should 
return 28. Now try: 

15 @ 30 + 13 

You should get the point 28@43 as an answer. Since you supplied a 
single value rather than a point, IBM Smalltalk adds the value to both 
the a: and y coordinates. 

The Class Rectangle 

A rectangle is defined by two points: its upper-left corner and its lower- 
right corner. Thus, we can make a point into a rectangle by supplying it 
with another point. Two methods handle this: 

m corner which returns a rectangle whose upper-left corner is the 
receiver of the message and whose lower-right corner is the coordi¬ 
nates of the argument, itself a point 

■ extent which returns a rectangle whose upper-left corner is the re¬ 
ceiver of the message and whose lower-right corner is calculated as 
the sum of the receiver and the argument 

For example, the following two rectangles are identical: 

1 @ 1 corner: 100 @ 100 
1 @ 1 extent: 99 @ 99 

You can change (or define) the size or location of a Rectangle with 
either of two methods: origimcorner: or origin:extent :. As you might expect, 
these methods operate similarly to corner: and extent: in the Point class. 
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You can shrink or expand a Rectangle in relative terms with the 
insetBy: method. (This method actually creates a new rectangle with the 
new size.) insetBy: takes a rectangle, point, or number as an argument 
and reduces both coordinates in both directions accordingly. Use Show 
It to evaluate the following expression in a Workspace to see the insetBy: 
method in action: 

(1 @ 1 extent: (99 @ 99)) insetBy: 10 

IBM Smalltalk returns a value that should be the rectangle defined as: 

11 @ 11 cornen: 90 @ 90 

Notice that the insetBy: method added 10 to the x and y coordinates 
of the upper-left corner and subtracted 10 from the coordinates of the 
lower-right corner. The result, then, is a Rectangle shrunk from the origi¬ 
nal (or inset on both corners) by a specific amount. 

We can perform numerous other operations on a Rectangle. These 
are largely self-explanatory and described in the IBM Smalltalk docu¬ 
mentation, so we won’t go into them in detail here. 



Instances of the class Point or Rectangle are not displayable objects but simply 
represent positions and areas. A subclass of CgDrawable is the object that actually 
holds the graphical image of points and rectangles. 



CHAPTER 


The Fifth Project: 

1 Graphing Application 



This chapter presents a graphic application that demonstrates the use 
of many of the classes and methods we examined in Chapter 10. The 
process will demonstrate a highly incremental approach to Smalltalk 
programming in which we build the application in three distinct stages. 

As with our previous projects, we begin by describing the application’s 
purpose and operation. Then we discuss its design in terms of the 
SmalltalkAgents class library and other considerations. We’ll construct 
the application in small segments, explaining each as we proceed. Fi¬ 
nally, we will integrate a variation of the application into to our existing 
SimplePIM module. 

Designing the Application 

This application will be a scaled-down version of a business graphing 
package. It will lack some functions and polish that a commercial pro¬ 
gram would have, but within its limited scope and purpose it will give 
the user a good deal of flexibility and control over the appearance of the 
graphs it produces. 

We will call the window of this application Plot Window. This window 
consists of two widgets. One widget displays the data being graphed. 
The other widget displays the graph itself in the form of bars. The user 
can choose the orientation of the bars (horizontal or vertical), spacing, 
proportionality, and pattern (which can be extended on a color display 
to specify the color of the bars). Obviously, a more robust application 
would allow the user more types of graphs. 

Data to be graphed can be entered directly by the user into the data 
pane in the application window, or they can be read from a file. Data 
entered into the data pane can also be saved into a disk file. 
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Figure 11-1. 


The basic structure of Plot application window 


Menus will provide the user with the ability to erase the plot, redraw 
it, return to default settings, and edit (cut, copy, or paste) data. 

Figure 11-1 shows the basic structure of the application, with the 
window showing its two widgets and all of the application’s menus. 

The Subpanes 

As you can see from Figure 11-1, this application’s window has two wid¬ 
gets. The one on the left is used to enter the data to be graphed. It is an 
instance of class CwText. The one on the right is where we graph the 
data. It is an instance of class CwDrawingArea. 


The Class PlotWsndow 

We create an entirely new class for this application and we’ll call this 
class PlotWindow. Because this is a largely self-contained application, 
we make it a descendant of the class Object. Start by creating this class 
and editing the class definition template to add the instance variables 
shell, drawArea, and data. Don’t forget to add the pool variables 
CwConstants and CgConstants. 
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Setting Up 

As before, we have included files on the disk to help you follow along or 
simply file in and run. These files will be in the Chapter 11 directory 
(folder). There are three of them: plotwndw.st, busywndw.st, and 
apptbkwn.st. The first of these is for the Plot Window application we are 
about to build, and the remaining two are for an application we will 
build at the end of the chapter. 

Unlike in previous chapters, these are not application but class files. 
Add them to the SimplePIM application by selecting SimplePIM in appli¬ 
cations browser and selecting fileln from the pop-up menu. The classes 
will be added i;o the application. The SimplePIM application can be loaded 
by filing in the Simplpim.app file found in the Chapter 9 directory (folder). 

Building the Application, Stage One 

As indicated at the beginning of this chapter, we’ll develop the Plot ap¬ 
plication using an incremental style. You will find this approach useful, 
for example, if you wish to demonstrate to a customer how an applica¬ 
tion will look before you spend a lot of time and energy developing its 
more complex behavioral methods. 

With this approach you’ll need to decide how many stages to use and 
how much functionality to incorporate at each stage. These are arbi¬ 
trary and application-specific questions involving computer science is¬ 
sues (addressed in many other books), so we can’t give you a lot of guid¬ 
ance. We can say, however, that the first stage of an incremental devel¬ 
opment in Smalltalk should produce a basic shell with little or no func¬ 
tionality. First stage development should demonstrate the application’s 
appearance, its basic menu choices, and its behavior in the broadest 
sense of the term. 

We have chosen to develop this application in three stages: 

1. Build a nonfunctional shell. 

2. Include a basic graphing capability, with most user options not 
yet incorporated. 

3. Include all user options. 
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The open Method 

As will often be the case in incremental Smalltalk program develop¬ 
ment, we begin by creating the method that sets up the application win¬ 
dow and its subpanes. We’ll call this the open method. We will continue 
to use our scheme of separate creation methods for each widget. There 
will be three methods: open , addText:, and addDrawArea:. The first two 
methods will be taken from the code we developed in Chapter 9 for the 
AppointmentBookWindow. The last we will have to build from scratch. 
The code for the first two methods appears below. You’ve seen every¬ 
thing in these methods in earlier chapters, so we won’t spend time de¬ 
scribing them here except to note that we removed the activate callback 
for now, and that the call to setUp is commented out: 

open 

"open a Plot window with one each text and drawing widget" 
j main form rowColumn J 

shell := CwTopLevelShel1 

createApplicationShel1: 'Plot Window' 

argBlock: ni 1 . 

shel 1 

addCal1 back: XmNwindowCloseCallback 
receiver: self 

selector: #closeWindow:clientData:callData: 
clientData: nil. 

main := shell 

createMainWindow: 'main' 
argBlock: nil. 
main manageChild. 

self addMenuBar: main, 
form := main 

createForm: 'form' 
argBlock: nil. 
form manageChild. 


self addText: form. 
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self addDrawArea: form, 
shell re a 1izeWidget. 
addText: aFcrm 

"Add a text widget to me" 
data := a Form 

createScrol1edText: 'data' 
argBlock: [:w | w width:55; 
editMode: XmMULTILINEEDIT; 
scrol1Horizontal: true; 
wordwrap: false], 
data manageChild. 

data parent setValuesBlock: [:w | w 
topAttachment: XmATTACFIFORM; 
bottomAttachment: XmATTACHFORM; 

rightAttachment: XmATTACHPOSITION; rightPosition: 15; 

1 eftAttachment: XmATTACFIFORM ]. 

Actually, v/e should make one comment concerning the text widget’s 
attachment. In the past, we’ve made all attachments to a form or other 
widgets. This time we want the text widget to occupy a percentage of the 
window. Resizing the window should resize the text widget but in the 
same proportion. We link the two sizes with the attachment type 
XmATTACHPOSITION and the message rightPosition: . Combined, they 
tell the form that the widget’s right side will attach so that it always 
maintains the same proportion to the form. 

We will borrow some more code, this time from CalendarWindow. We 
need the close:clientData:callData method. From the ifTrue: block on 
the second to last line, remove the code and leave the block empty for 
now. Here is how the modified method should look: 

closeWindow: aShell clientData: clientData callData: callData 
"Process the window close callback." 


| answer | 
answer := 

(CwMessagePrompter for: aShell) 

messagestring: 'Quit the Plot Application?'; 
iconType: XmlCONQUESTION; 
buttonType: XmYESNO; 
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prompt. 

answer 

ifTrue: []. 
callData doit: answer 

Next we look at the addDrawArea: method. To build this widget, we’ll 
take the same approach we take to build other widgets. The only trick here 
is setting the width and height to ensure a minimum sized window. The 
attachment should be as expected. We will add callbacks as we need them. 

addDrawArea: aForm 

"Add a drawing area widget to me" 
drawArea := aForm 

createDrawingArea: 'draw' 

argBlock: [:w | w width:200; height: 200 ]. 

drawArea manageChild. 

drawArea setValuesBlock: [:w | w 

topAttachment: XmATTACHFORM; 
bottomAttachment: XmATTACHFORM; 
rightAttachment: XmATTACHFORM; 

leftAttachment: XmATTACHWIDGET; leftWidget: data]. 


Methods for the Text Widget 

The text widget where the data will be entered requires two basic meth¬ 
ods: dataMenu: and redraw:. We have seen equivalents of the first method 
in the addMenuBar: method we created earlier. This time we will create 
a method for each menu and call them from addMenuBar:. This ap¬ 
proach gives us some flexibility in extending our prototype menus to the 
final product’s menus. We can use the addMenuBar: method from 
AppointmentBookWindow as a template and change the names of but¬ 
tons and callbacks. The code for this method appears below: 

dataMenu: menuBar 

"create the data menu" 

| form subMenu item | 

form := menuBar createPul1downMenu: 'pulldown' 
argBlock: nil. 

subMenu:=menuBar createCascadeButton: 'Data' 
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argBlock: [:w| w subMenuId: form]. 
subMenu manageChild. 

item := form 

createPushButton: 'Accept' 
argBlock: ni1 . 

item addCal1 back: XmNactivateCa11 back 
receiver: self 

selector: #redrawc1ientData:calfData: 
clientData: nil. 
itern manageChi1d . 

item := form 

createPushButton: 'Cut' 
argBlock: nil. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #cutText:clientData:callData: 
clientData: nil. 
item manageChild. 

item := form 

createPushButton: 'Copy' 
argB1ock: nil. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #copyText:clientData:callData: 
clientData: nil. 
item manageChild. 

item := form 

createPushButton: 'Paste' 
argBlock: nil. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #pasteText:clientData:callData: 
clientData: nil. 
item manageChild. 
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We need to get the contents of the text widget and pass these contents 
to a method we will build later. It will convert the new contents into an 
OrderedCollection; we can use this collection to draw a new plot. We 
call this new method redraw the name explains the redraw:clientData:- 
callData statement in the dataMenu: method for the window. 

The redraw: method retrieves the contents of the pane and for now 
simply creates a new string of data. As you can see below, the newData: 
method does nothing. Later, we’ll hook it up to the data coming out of 
the text pane and set the context for drawing a new chart based on the 
new information. 

Here is the redraw: method: 

redraw: widget clientData: clientData cal 1 Data: cal 1 Data 
"redraw the plot" 

| newData | 

newData := data getString. 
self newData: newData. 

Here is the skeleton of the newData: method: 
newData: aString 

A ' ' 


The menu for this widget in this preliminary version will allow the 
user to choose from the options: Accept, Copy, Cut, and Paste. Later (in a 
real-world situation, such decisions would probably be based on the 
customer’s feedback) we will add other functions to this menu. For the 
moment, we’ll leave the prototype in this state. 

We can quickly add the edit functions by taking the methods of the 
same names from the AppointmentBookWindow. Copy these three meth¬ 
ods, change references to text so they refer to data , and save it. Presto! 
Instant editing capability. 

Notice that the redraw: method, called in response to the accept menu 
event, does nothing in this prototype version. Later we’ll fill it in with 
code that will make it change the plot when the data in the CwText 
changes. For now we need to include the method to avoid the error that 
would otherwise arise if the user selected Accept from the menu. 
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Methods for the CwDrawingArea Widget 

From the open method you can see we need to define a method for the 
CwDrawingArea widget to avoid compilation errors and to complete 
work on our semifunctional prototype version of the Plot application. The 
plotMenu method creates the menu for the Plot widget. Here is its code: 

plotMenu: meruBar 

"Create the plot menu" 

| mainForm main item | 

mainForm := menuBar createPul1downMenu: 'main' 
argB'ock: nil. 

main :=menuBar createCascadeButton: 'Plot' 
argBlock: [:w| w subMenuId: mainForm ]. 
main manageChild. 

item := mainForm 

createPushButton: 'Erase' 
a rgBlock : nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #clear plot:client Data:cal 1 Data: 
clientData: nil. 
itern manageChi1d . 

item := mainForm 

createPushButton: 'Horizontal Bar' 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #setHorizontal:clientData:callData: 
clientData: nil. 
item manageChi1d . 

item := mainForm 

createPushButton: 'Vertical Bar' 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 


receiver: self 
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selector: #setVertical:clientData:cal 1 Data : 
clientData: nil. 
item manageChi1d. 

Notice that the menu allows the user to erase the current graph or to 
choose either a horizontal bar or a vertical bar. 


Adding the Menu Bar 

Finally, we need the addMenuBar: method that will call the menu meth¬ 
ods. The code simply creates a menu bar for the application, then tells 
each menu to build itself on this menu bar. The code follows: 

addMenuBar: aMainWindow 

"Add the two menu items to the menubar" 

| item menuBar form subMenu subMenu2 form2 | 

menuBar:= aMainWindow createMenuBar: 'menu' 
argB1ock: nil. 
menuBar manageChild. 

self dataMenu: menuBar. 
self plotMenu: menuBar. 

As you can see, this method knows how to delegate responsibility, 
leaving it with little work of its own. 

Demonstrating the First Version 

In keeping to the principle presented earlier, we’ll define an example 
class method for our new PlotWindow class. Like most such methods, it 
is quite simple: 

example 

"Open a PlotWindow for demonstration purposes" 

PlotWindow new open. 
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We can demonstrate how this window will look and describe its be¬ 
havior by executing the following line of code: 

PlotWindow example 

You can now display the two widget menus, show how the minimum 
size of the window is constrained, collapse the window, and describe 
what will happen when the menu choices are selected in the finished 
application. 

Of course, we haven’t defined the methods that will be called when 
the menu choices are actually made, so if you or the user selects a menu 
choice at this point, an error walkback will appear. Some prototype de¬ 
signers would take our design a step further and define dummy methods 
for all these menu choices. (Doing this or not will depend upon the appli¬ 
cation and the nature of the user for whom the demonstration is being 
presented.) Incidentally, the menu options in the CwText call the call¬ 
back methods we added, so the Data menu will work as expected. 

Another thing you can demonstrate to the user is that attempting to 
close the window results in a confirmation window. 

We’ll learn more about text-editing classes and methods in Chapters 
12 and 13. 

This little application is a reasonably effective prototype. You can show 
the user the window and its widgets; demonstrate its movement, resizing, 
and collapsing; examine the menu choices you’ve decided to include; 
and show how data entry and editing will work in CwText. And you’ve 
had to write very little code to get this far. 

Building the Application, Stage Two 

In the second stage of our application construction, we will add the abil¬ 
ity to draw the bar graphs. We will also define and initialize factors that 
the user will later be able to adjust, affecting the style, appearance, spac¬ 
ing, and other characteristics of the graphing bars. Finally, to make the 
application complete, we will fill in the newData: method that will up¬ 
date the contents of the drawArea widget when the user modifies the 
data in the CwText. 
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Plotting the Plots Arguments 

Before we can write methods that will draw the bars, we need to deter¬ 
mine the factors that make up the size, appearance, and positioning of 
the bars in a graph. Then we can determine which factors to control 
within the application and which ones to allow the user to modify. That 
will give us the information we need to create an initialization routine to 
set up default values for these variables and to write the horizontalBar: 
and verticalBar: bar-generating methods to make use of these variables. 

Three of these values are self-evident: the width of each bar, the spac¬ 
ing between bars, and the pattern or color with which to fill the bars. 

A study of data graphing techniques reveals one other characteristic 
of a bar in a graph that we may wish to accommodate. We need some 
way to control the scaling of data in the CwBrawingArea so that we can 
convey the maximum amount of information to the user in the space 
available. The scaling needs to adjust to the ranges of values the user 
enters. For example, if the user enters a series of values within the range 
of 10-50 and then later wants to plot a series of values ranging from 
100-500, we don’t want the second plot to be ten times as wide as the 
first (or, conversely, for the first plot to be one-tenth as wide as the sec¬ 
ond). This would result in either minuscule bars that are very hard to 
differentiate from one another at low ranges or bars so wide we couldn’t 
see their ends. 

We will use a stretch factor to accommodate this need. This is an 
integer by which we will multiply each data value to be plotted. 

We want the user to be able to control the four constraints on a bar 
graph. In the final version of the application, then, we’ll devise a method 
to allow the user to modify any or all of these characteristics without 
having to modify the application code. For this version, however, we’ll 
establish reasonable default values for all these variables and define a 
method to initialize them. This approach is preferable to hard-coding 
the values directly into the bar-graphing methods, since it will make it 
easier later to modify them either in the code (as we develop and experi¬ 
ment with it) or from a menu (when we make that capability available to 
the user). We will, however, add the methods necessary to permit the 
user to determine which type of graph to use. 
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The initialize Method 

Now that we know what variables we need to accommodate, we can 
easily write a setUp method that will set up the default arguments for a 
bar graph. We need to initialize one other factor—the type of bar to be 
drawn. We had already determined in the prototype to let the user choose 
a horizontal or vertical bar. We’re going to start out arbitrarily with 
horizontal bars. 

Here is the code for the setUp method, which we’ll call from the open 
method: 

setUp 

11 i nit the bar style, width spacing, factor and 
create a graphic context to use" 
plotSelector := #horizontalBar:. 
factor := 3. 

barWidth := 2 * data display defaultFontStruct height. 

barSpacing := data display defaultFontStruct height. 
barGC : = drawArea window 

createGC: None values: nil. 

Notice that we use the default font height of the data widget as the 
yardstick by which to set up default values for width and spacing of the 
bars. This approach is preferable to hard-coding a value, since it allows 
the display to be flexible depending on the system and the font it uses. 
This flexibility is especially important in a cross-platform environment 
like IBM Smalltalk. 

We also create and initialize a graphic context, CgGC. Before we can 
draw we need a GC associated with the CwDrawingArea to which we 
can send drawing instructions. You may recall that a CwDrawingArea 
does not automatically have a GC object, so we must create one for the 
window and assign it to an instance variable for easy access. Inciden¬ 
tally, the keyword None is a CgConstants pool dictionary constant that 
indicates no values are being set, and that default values are to be used. 

Including this method and defining these instance variables necessi¬ 
tate changing our earlier code to declare these instance variables in the 
class definition. We’ve done this before, so we won’t reproduce the code 
here. As we go along in this development, we’ll add other instance variables 
to the list as well. We’ll point these out as they arise; be sure to add them 
to the class definition. You’ll want to add the instance variables before 
adding the method and add the new code to the end of the open method. 
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Before we forget, let’s add some code to the closexlientDataxallData 
method, which will free the GC when the window is closed. Actually, we 
should create a separate method to handle closing issues that we will 
call from this method. At the second from the bottom line of the method, 
in the empty ijTrue: block, add the following: 

self closing 

The closing method, for now, looks like this: 

closing 

"Clean up and get ready to close" 
barGC freeGC 


Drawing the Bars 

With the constraint variables defined, we are ready to write the methods 
that actually draw the bars in the CwDrawingArea. They are similar to one 
another, so we’ll take a close look at the horizontalBar : method and then 
reproduce the verticalBar: method with little additional commentary. 

The drawing process can be thought of as simply looping through 
each data element, calculating and drawing each bar. Here is the code 
for the horizontalBar: method. We’ll analyze the way the bars are calcu¬ 
lated and drawn in a moment. 

horizontalBar: theData 

"Draw a horizontal bar plot of the data, an 
ordered collection of integers." 

| x y win] 
x := y:= 0. 

win := drawArea window. 

win clearWindow. 
theData do: [.: v a 1 u e | 
w i n 

fi11Rectangle: barGC 
x: x 
y: y 

width: (factor * value) 
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height: barWidth. 
y : = y + barWidth+ barSpacing. 


Calculating and Drawing the Bars 

All the drawing commands are sent to the CwDrawingArea instance’s 
window, a CgWindow. Once we’ve cleared the window, we use a do: 
block to loop through the data in the variable theData that is passed as 
an argument with the horizontalBar: message. (We will see shortly how 
this variable is determined from the values entered by the user in CwText. 
This processing is handled by the newData: method that is called as a 
result of the occurrence of the save: event.) 

Each entry in this variable is an instance of class OrderedCollection. 
We pass the GC along with the starting point and extent of the rectangle 
to the method fillRectangle:x:y:ividth:height:, which does all the work of 
positioning and drawing. All we have to do is increment the y-axis point 
to position the next rectangle and repeat the process. 

Notice that we use the stretch factor, which we stored in the instance 
variable factor , to scale each element in the data collection as we draw 
it. Note, too, that we determine where to place the pen for the next hori¬ 
zontal bar by adding the spacing and width of the bars set up in the 
initialize routine. 


The verticaSBar Method 

Now that we understand the horizontalBar: method, we can look at its 
counterpart for drawing vertical bars. Here is the code for the werticalBar: 
method: 

verticalBar: theData 

"Draw a vertical bar plot of the data, an 
ordered collection of integers." 

| x y win result] 
x : = C. 

y := drawArea height - 30. 
win := drawArea window, 
win clearWindow. 
theData do: [rvalue | 
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wi n 

fi11Rectangle: barGC 
x: x 

y: y 

width: barWidth 

height: (value * factor) negated, 
x := x +barWidth + barSpacing. 

]. 

The significant differences between this method and the horizontalBar: 
method is that we used the Number method negated to ensure the prod¬ 
uct of the value and factor is negative. This results in the rectangle being 
drawn backwards, with the starting point at a location 30 pixels from 
the bottom of the window. 

Defining Graph Selection Methods 

Remember from the discussion of the initialize method that we start the 
Plot application with horizontal bars as the default plot type. We store 
this value in the instance variable plotSelector . The Plot menu invokes 
two specific methods— setHorizontal and setVertical —that determine the 
plot type to use. These methods must set the value of plotSelector in 
accordance with the user’s wishes. Here is the code for these methods; 
they use the callback naming scheme, since these methods will be called 
from the menu. 

setHorizontal: widget clientData: clientData cal 1 Data: cal 1 Data 
"Set the plot type to horizontal bar" 
plotSelector := #horizontalBar:. 

setVertical: widget clientData: clientData callData: cal 1 Data 
"Set the plot type to horizontal bar" 
plotSelector := #vertical Bar:. 
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The clearPlotMet hod 

We need to create another CwDrawingArea menu method to erase the 
graph. This turns out to be surprisingly easy. No need to determine where 
graphic objects appear and draw over them; we merely tell the drawArea 
window to clear itself. Here’s the code (again, this is a menu callback): 

clearPlot: w'dget clientData: clientData callData: callData 
"Clear the plot area" 
drawArea window clearWindow. 


The newData: Method 

The final method we need for this stage of our application’s develop¬ 
ment is the newData: method that converts the data into a usable form 
and creates a new plot with the resulting data. Recall that in our proto¬ 
type, we created a dummy version of this method. It is now time to round 
it out. Here is the code: 

newData: aString 

"Accept the user input, and redraw the chart with this 
data. Answer true" 

| input token | 

input := ReadStream on: aString. 

plotData := OrderedCol1ection new. 

[ input atEnd ] 

whileFalse: [ 

token := input nextWord. 
token > 0 

ifTrue: [ plotData addLast: token asNumber]]. 

self newPlot. 

A true. 

This method first converts its string argument to a stream. The string 
is the data entered in CwText There are no built-in methods to parse a 
string directly, so we convert it to a stream first. 

Next, we define an instance of the class OrderedCollection called 
plotData to hold the parsed values. Don’t forget to add plotData as an 
instance variable to the class definition. 
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We work our way through this collection an item at a time, adding 
each new “word” (in this case, a number) to the end of the collection 
until we have converted all elements of the stream to an Ordered- 
Collection. Notice that we do not want to plot negative numbers, so we 
ignore numbers less than zero. 


A Generic Plot-Drawing Method 

The newData: method ends with the system ready to create the bars in 
the plot. Should we send the horizontalBar: message or the verticalBar: 
message? That depends on the value of the instance variable plotSelector , 
as you know. In good OOP style we’ll create a method (we call it newPlot) 
that doesn’t need to know the type of bar that is being plotted. It just 
uses the current value of plotSelector in a perforrrv.with: statement. Here’s 
the code: 

newPlot 

"If there is data to plot, plot it using the currently 
selected set of plot parameters" 

(plotData notNil and: [plotData notEmpty ]) 

ifTrue: [ self perform: plotSelector with: plotData]. 

Demonstrating the Second Version 

This version of the program is fully functional, so we can demonstrate 
all of its capabilities. Use the example approach or just call the open 
method directly and create a new PlotWindow. It should look exactly as 
it did earlier during the demonstration of the prototype. 

Now enter a few values. Keep them in the range of 1 to 120 for the 
moment because the stretch factor of 3 that we’ve applied makes values 
larger than about 120 disappear off the right edge of the widget. 

After you enter a few values, select the Accept option from the data 
pane’s pop-up menu or from its window menu bar equivalent. A hori¬ 
zontal graph of the data elements in the default black should appear in 
the CwDrawingArea, similar to that shown in Figure 11-2. 

Now choose the Erase option from the Plot menu and the graphing 
area will be clear. Choose Vertical Bar from this same menu. 

Put the cursor into the data widget and make some change to the 
contents. You can leave the values the same by simply pressing (Enter) at 
the end of the list, or you can edit one or more values. You can even 



CHAPTER 11: A GRAPHING APPLICATION 


289 


clear all the values from the pane and enter new ones. As soon as you 
select the Accept option from the Data menu the new vertical graph 
should appear, looking like the one in Figure 11-3. 

You should also collapse, resize, move, and close the window to be 
sure all of those built-in functions work as expected. 



A Sample horizontal bar graph 
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Building the Application, Stage Three 

In this final stage of building the Plot application, we’ll add the following 
functionality: 


b User selection and alteration of the fill pattern, spacing, width, and 
stretch factor for the bars, using menus and submenus 

■ File-based data retrieval and storage 

■ More intuitive and usable redrawing of the plot on user demand 


These changes have nothing to do with graphics, so you can skip this 
part, if you choose. But if you are interested in any of the above design 
issues, you will find the small amount of reading and the few code changes 
outlined in the rest of this chapter interesting. 


User Selection of Graph Arguments 

As you’ll recall, we have three graph arguments the user should be al¬ 
lowed to change: fill pattern, spacing between bars, and width of indi¬ 
vidual bars. The processes for these changes vary only in small details 
from one choice to another. We’ll examine the first closely and look briefly 
at the remaining two. 

There are many ways we could permit the user to change one of these 
characteristics of a plot. We could create one large menu, for example, 
that listed all of the options. Or we could design a pane for the window to 
contain buttons with which the user could activate these modifications. 

But let’s extend our experience with Smalltalk by using a design that 
we have not seen before. We’ll build a series of menus that appear to 
cascade from one to another. We’ll do this by adding a new item to the 
plotMenu method to generate a menu from which the user will pick the 
characteristic to change. Depending on the user’s choice on this menu, 
another menu may appear from which the user can choose the desired 
value for the option. 


Changing the plotMenu Method 

We’ll add three choices to the plotMenu method of our earlier version of 
this application. The first change will allow the user to redraw the plot 
without having to change the data in the CwText by forcing an update of 
the CwDrawingArea unless the data pane is empty. The second will dis- 
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play a menu of options the user can change. The last will return all the 
characteristics of a plot to their original default values. This will encour¬ 
age users to experiment with other settings because they’ll know they 
can always revert to the defaults. Here is the code for the rather lengthy 
new plotMenu: method: 

plotMenu: menuBar 

"create the Plot menu and its Options and Color submenus" 

| mainForm optionForm colorForm main option color item | 

mainForm := menuBar createPul1downMenu: 'main' 
argBlock: nil. 

main :=menuBar createCascadeButton: 'Plot' 
argBlock: [:w| w subMenuId: mainForm ]. 
main manageChild. 

itern := mainForm 

createPushButton: 'Erase' 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #clearPlot:clientData:ca11Data: 
clientData : nil. 
item manageChild. 

i tern :== mainForm 

createPushButton: 'Redo Plot' 
a rg B1ock : nil. 

item acdCal1 back: XmNacti vateCal1 back 
receiver: self 

selector: #redrawPlot:clientData:callData: 
clientData: nil. 
item manageChild. 

item := mainForm 

createSeparator: 'sep' 

argBlock: [:w | w separatorType: XmSINGLELINE]. 
item manageChi1d. 

item := mainForm 

createPushButton: ' Horizontal Bar' 
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argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: //setHorizontal:clientData:callData: 
clientData: nil. 
item manageChi1d. 

item := mainForm 

createPushButton: 'Vertical Bar' 
argBlock: ni1. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: //setVerti cal:clientData:ca 11 Data: 
clientData: nil. 
item manageChi1d . 

item := mainForm 

createSeparator: 'sep' 

argBlock: [:w | w separatorType: XmSINGLELINE]. 
itern manageChi1d . 

"Create the option Menu" 

optionForm := mainForm createPul1downMenu: 'option' 
argBlock: nil. 

option :=mainForm createCascadeButton: 'Options' 
argBlock: [:w| w subMenuId: optionForm ]. 
option manageChild. 

item : = optionForm 

createPushButton: 'Stretch Factor' 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: //factor: cl i entData : cal 1 Data : 
clientData: nil. 
item manageChild. 

item : = optionForm 

createPushButton: 'Bar Width' 
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argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #barWidth:clientData:callData: 
clientData: nil. 
item manageChi1d . 

item := optionForm 

createPushButton: 'Bar Spacing' 
argBlock: nil. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #barSpacing:clientData:callData: 
clientData: nil. 
item manageChi1d. 

"Create the Option menu Color submenu" 

colorForm := optionForm createPul1downMenu: 'color' 
argBlock: nil. 

color :=optionForm createCascadeButton: 'Color' 
argBlock: [:w| w subMenuId: colorForm ]. 
color manageChi1d. 

item :== colorForm 

createPushButton: 'Black' 
argB1ock: nil. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #color:clientData:callData: 
clientData: 'black', 
item manageChi1d. 

item colorForm 

createPushButton: 'Dark Grey' 
argBlock: nil. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #color:clientData:callData: 
clientData: 'dim gray'. 
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item manageChi1d. 

item := col or Form 

createPushButton: 'Light Grey' 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #color:cl i entData-.callData: 
clientData: ' gray80'. 
item manageChi1d. 

"Add last menu item to Plot Menu" 

item := mainForm 

createSeparator: 'sep' 

argBlock: [:w | w separatorType: XmSINGLELINE]. 
item manageChi1d. 

item := main Form 

createPushButton: 'Restore Defaults ' 
argBlock: ni1. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #resetDefaults:clj entData:cal 1 Data : 
clientData: nil. 
item manageChi1d. 

The two new Plot menu button’s callbacks simply call the existing 
methods newPlot and setUp, which are already in place; these new menu 
alternatives give the user a direct way to invoke them. As you can see, 
the names of the methods have been established as redrawPlot: and 
resetDefault :. This is getting to be old hat, so just add these new meth¬ 
ods using these names and append the callback format to the methods. 
We won’t give you the code. 
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Methods to Select the Fill Pattern 

We begin examining the option-changing methods by looking at the 
method used to choose the type of fill pattern for drawing bars in the 
graph. As you can see from examining the plotMenu: method, the user 
can choose from among three colors, or patterns: black, dark gray, and 
light gray. Each menu option for selecting one of these patterns has a 
corresponding clientData with name of the color. This method simply 
takes the name passed as clientData , looks it up, and assigns it as the 
barGCs foreground color. The tricky part is getting the right color. We 
do this by requesting a color from the default palette that most closely 
resembles the color we want. This is the correct technique to use to 
ensure colors are similar across platforms. You may have found, if you 
have more than one machine platform, that the color assignments we 
made in Chapters 7 and 9 using the CgRBColor class have not always 
had the expected results. We will fix this problem later in the chapter by 
adapting this technique to those classes. Here is the listing: 

color: widget clientData: clientData callData: cal 1 Data 

"Accept the user input, and redraw the chart with this 
data" 

| newData | 

barGC set Foreground: (CglndexedPalette default 

nearestPi xel Val ue: ( drawArea screen lookupColor: 
clientData asString)). 

With this method defined, we can now create more interesting bars in 
our chart. Let’s change the default behavior of the bars, which currently 
draws rectangles with no fill color or pattern. Just add this line to the 
end of the setUp method: 

self color:ni! clientData: 'black' callData: nil. 

(Substitute the appropriate color name if you prefer the default bars 
in your charts to be dark gray or light gray.) The next time you draw a 
bar graph, the bars will be the color designated in the setUp method. 
Note that we can call the callback method this way since it does not use 
the other arguments. Of course, you must take care that the proper ar¬ 
guments are passed. 
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The barSpacing , barWidth , and facfor Methods 

The methods that change spacing and width of the bars in the graph as 
well as the stretch factor by which data are scaled to the CwDrawingArea 
are so similar that it makes sense to present them together. The only 
difference among them lies in the instance variable to which the user’s 
response is assigned. 

These methods present a validation problem. Up to now, when we 
provided the user with a menu of choices from which to respond to a 
question, as with the choice of what color pen to use to draw the bars, 
we prevalidated the user’s answer. It was impossible for the user to en¬ 
ter an invalid or illegal response. For example, in response to the 
dataPane’s menu above, the user cannot answer “purple with green polka 
dots.” However, in the case of the spacing and width arguments, the 
program depends on the user to provide a number. We need to ensure 
that the user actually enters a number. Not only that, we have to guard 
against outlandishly large or small values that would result in unusable 
graphs. 

To accomplish these purposes, we’ll create a new method called 
promptFor:default:convertWith:validateWith :, which will ask the user for 
an entry, provide a default value for the user to accept, and then validate 
the user’s input. We’ll look at this method in the next section. For now, 
you can see how it works in practice by examining these two methods: 

barSpacing: widget clientData: clientData cal 1 Data : cal 1 Data 

"Validate the user input, if valid accept it, if not tell user" 

| newData | 
barSpacing := 

self promptFor: ' Bar Spacing ' 
default: barSpacing 
convertWith: #asNumber 
validateWith: 

[: v | ((v islnteger) and: [v > 1]) and: [v < 16] ]. 

barWidth: widget clientData: clientData callData: callData 

"Validate the user input, if valid accept it, if not tell user" 

| newData val| 
barWidth := 

self promptFor: ' Bar Width ' 
default: barWidth 
convertWith: #asNumber 
validateWith: 
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[:v | ( v islnteger and: [v > 2]) and: 

[v < 51] ]. 

factor: widget clientData: clientData callData: callData 
"Prompt fo rt a new value of the data stretch factor. If the 
user's response is not nil, validate it. If it is not 
valid, tell the user, otherwise accept it." 

| newData val | 
factor := 

self promptFor: ' Stretch Factor ' 
default: factor 
convertWith: #asNumber 
validateWith: 

[: v | ((v islnteger) and: [v > 0]) and: [v < 51] ]. 

Notice that in each of these methods we use the new prompting method, 
with appropriate arguments, to ask the user for a new value for the 
corresponding instance variable. The validation uses the islnteger method 
understood by all objects to ensure that the entry is not only numeric but 
a whole number. It then checks the range of the entry to be sure it is 
within reasonable limits. 

The Validation Method 

Here is the code for the method we used with barSpacing:, barWidth:, 
and factor: above to prompt the user for an entry and to validate the 
user’s response: 

promptFor: aString default: anObject convertWith: aSymbol validateWith: 
a B1ock 

"Prompt the user to supply a new value for 
what is described by aString. Answer nil, anObject or 
user response, for no, invalid or valid response" 

| response | 

response := CwTextPrompter new 
title: 'New Data For: ', aString; 

messagestring: 'Enter new value for: ', aString; 

answerstring: anObject printstring; 
prompt. 

response isNil ifTrue: [ A an0bject]. 
response := response perform: aSymbol. 
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(aBlock value: response) 

ifTrue: [ A response] 
ifFalse: [ 

CwMessagePrompter new 

title: 'Invalid Value Entered'; 
messagestring: response 
printString, ' is not a valid ', aString; 
buttonType: XmOK; 
iconType: XmlCONERROR; 
prompt. 

A anObject]. 

This compact, general-purpose method uses the CwTextPrompter 
class’ methods. We used other methods of this class earlier in the book, 
so it is no stranger to us. 

Our new method takes four arguments. The first is a string that com¬ 
pletes the user prompt “Enter a new value for” with the appropriate 
characteristic or property you are prompting the user to change. The 
second argument is a string that represents the default value to be used 
if the user doesn’t intervene. The third argument is the symbol of the 
method to use to convert the response to type of class the receiver ex¬ 
pects. The final argument is a block that this method executes. The block 
must return a logical value (true or false) so that our new method can 
respond accordingly. 

You can now see how the barSpacing method works. It presents a 
prompter with the label “Enter a new value for Bar Spacing” and places 
the current value of the instance variable barSpacing into the prompter 
as a default response. If the user does anything but delete this default 
response, the method checks to ensure that the user’s entry is a valid 
integer with a value between 2 and 15. The barWidth and factor meth¬ 
ods are identical. 


File-Based Data Retrieval and Storage 

The second major change we want to make to our Plot application will 
allow the user to store data elements in a disk file from which they can 
be retrieved. To do this, we need to modify the menu in the data pane to 
offer the options of loading and saving data from and to a file, and we need 
to write the methods that will handle the file inpul/output processing. 
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The Modified dataMenu Method 

We need to add only two items to the menu that appears in the Data 
menu. By now you should be familiar with the format of the menu method, 
so we will display the code segments for the added menu items. Place 
these after the Accept item and before Copy. The code segment for the 
menu items and enclosing separators follows: 

item := form 

createSeparator: 'sep' 

argBlock: [:w | w separatorType: XmSINGLELINE]. 
item manageChfld. 

item := form 

createPushButton: 'File In' 
argBlock: nil. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #fi1eln:cllentData:cal 1 Data: 
clientData : nil. 

1 tern manageChi1d. 

item := form 

createPushButton: 'File Out' 
argB1ock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #fileOut:clientData:callData: 
clientData: nil. 
item manageChi1d. 

item := form 

createSeparator: 'sep' 

argBlock: [:w | w separatorType: XmSINGLELINE]. 
item manageChild. 
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The fileln Method 

Here is the code for the method that will be called when the user indi¬ 
cates a desire to load some data previously stored in a file: 

fileln: widget clientData: ignore callData: callData 
"Use a platform file dialog to prompt 
user for filename to read. Open a filestream and 
read the stream to the data text widget" 

| path file | 

path := CwFi1eSelectionPrompter new 
title: 'File In Data' ; 
searchMask: '*.dat'; 
prompt. 

file := CfsReadFi1eStream open: path, 
data setstring: String new. 

data insertAndShow: data getLastPosition value: file contents, 
file close. 

self newData: data getString. 

We use the CwFileSelectionPrompter class to create and set up user 
interaction with a platform file dialog. You can probably deduce that the 
searchMask: method defines the default extension for the file (in this 
case *.dat). Finally, we send the CwFileSelectionPrompter object the 
prompt message to retrieve the user’s response. 

Once we have a valid stream, we use the CwText method 
insertAndShow:value: to refresh the contents of the data pane with the 
contents of the file. Then we close the stream. Finally, we use the newData: 
method to update and redisplay the plot for the newData: 

The fileOut Method 

The fileOut method writes information from CwText to a DOS file and is 
almost identical to the fileln method. Here is its code: 

fileOut: widget clientData: ignore callData: callData 
"Use a platform file dialog to prompt 
user for filename to write to. Open a filestream and 
write the stream to the data text widget" 

| path file | 
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path := CwFi1eSelectionPrompter new 
title: 'File In Data'; 
searchMask: **.dat'; 
prompt. 

file := CfsReadWriteFi1eStream openEmpty: path, 
file lextPutAll: data getString. 
file close. 

This method is similar to the Jileln method. This time, though, we 
place the data text widget contents into the file. Also, we don’t need to 
update the dataPane’s contents since we are not changing them. In ev¬ 
ery other respect, this method is identical to the fileln method. 

This approach should work fine, except that the openEmpty: method 
will overwrite the file even if it already exists, which may not be such a 
good idea if you want happy users. We will deal with this issue in Chap¬ 
ters 14 and 15. 

Integrating with the SiiplePIl 

Now that we have a fine stand-alone application, let’s see if we can find 
a role for it in our SimplePIM application environment. At a glance you 
can see the dates on which you have appointments, but to see the num¬ 
ber of appointments you must go to the Appointment Book, which dis¬ 
plays only one day’s appointments at a time. Perhaps it would be nice to 
see the number of appointments scheduled for each day or for a given 
period, say a week. A graph showing the number of appointments per 
day would demonstrate even better your daily obligations. We could even 
use our knowledge of color to create a color scale for the busyness of 
each day. Extremely busy days would be in red; moderate days, in yel¬ 
low; and open or light days, in green. 

By linking the application into our existing application framework, 
we can have it make requests and be notified of events. For example, 
when a new date is selected, we can automatically graph appointments 
for the ensuing week. We will also need to make a request of the Ap¬ 
pointment Book for the appointments in a given period. 

By subclassing the PlotWindow class, we can create a specialized 
PlotWindow for the SimplePIM. 
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To avoid typing in a good bit of code, load in the bosywndw.st and apptbkwn.st files 
you'll find under the chapll folder on the disk accompanying this book. 


Create a PlotWindow subclass called BusynessWindow and populate 
it with the instance variable ac , for our application controller link, and 
the CwConstants and CgConstants pool dictionaries. 


Creating a Real Team Player 

To be a team player, in our application framework, we need to add some 
code to our new application. How much participation in the framework 
should our application have? It should be part of the activate events, 
since we want it to be brought to the front, along with the other applica¬ 
tions. It needs to make requests and to be notified of events. We do not 
want it included in the one-close-we-all-close event, since the user may 
not want to view the chart at all times. Also, it should not be launched on 
startup but should instead be launched from one of the other applica¬ 
tions. This is in keeping with the idea that this view is displayed only at 
the user’s discretion. 

With these decisions made we can proceed with code development. 
As you may have guessed, much of the code required can be borrowed 
from one of the other application classes. We can use the activate frame¬ 
work without modification. Let’s bring those methods over to our new 
class. To jog your memory, the methods we want are activate , 
activate:clientData:callData :, close , remove Activate, and reset Activate. 
Copy them as is into the new application. We also need the controller: 
method so the application controller can tell us about it, so copy this 
method as well. 

Next, we need the application to respond to the dateChanged: event 
message. The method should respond by using the date passed to it to 
calculate the number of appointments for each date in the given date’s 
period, set the label of the window to the first date of the period, and 
update the chart with the new data. 

The statement “calculate the number of appointments” above is akin 
to the cartoon of a scientist who has completed a long, complicated math- 
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ematical formula, only to have it pointed out by a colleague that the 
phrase “then a miracle happens” may need some further explanation. 

Fortunately we don’t need a miracle here, just a moderately intelli¬ 
gent piece of code. In fact, this sounds like it would work best as a sepa¬ 
rate, generic method. We will put off working on this method until we 
finish the dateChanged: method. 

Based on our discussion above, here is the code for the dateChanged: 
method. 

dateChanged: aDate 

"calendar date has changed, so determine 
dates needed, ask apptbook for them, plot 
them and update display with new data" 

|appts dates stream | 
dates := self datesSurnounding: aDate. 

self setLabel: dates first. "Use first date in collection as 
period start date" 

appts := (ac request: #numberOfAppointmentsIn: 

from:#AppointmentBook with: dates), 
stream := ReadWriteStream on: String new. 
appts do: [:a | stream nextPutAll: a printstring; cr]. 
appts := stream contents, 
self rewData: appts. 
self cisplayNewData: appts. 

We use a stream to create a string with carriage returns (CRs) so that 
it can be added to the display and appear as if the user typed it in. The 
use of the stream message cr will add the necessary CR characters to the 
stream. Since different platforms use different characters for CRs, we 
don’t want to assume a particular character sequence and thus incur 
platform dependence. The stream approach will guarantee that our dis¬ 
play format will work with the fileln and fileOut methods. Besides the 
method on hold, we have created the need for two additional methods, 
as well as one in another class. We will add the last one to our “hold” list 
and look at the two local methods. 

The first of these methods is setLabel which will display the new date’s 
period label, in the form of “Week of Monday December 26, 1994.” The 
chart will plot all dates in a given period, with the label displaying the 
starting date of the period. Here is the instance method’s code: 



setLabel: aDate 


"Set the label according to the attributes 
of aDate." 

| string | 

string := period,' of ' .aDate dayName. 
string := string,' ',aDate monthName,' ', aDate 

dayOfMonth printString , ' , ',aDate year printstring, 
shell title: string. 

The other method we call for is displayNewData which will be re¬ 
sponsible for putting the newly collected data into the data text widget. 
We can construct this method from code taken from the superclass 
method fileln . Which brings up an interesting design decision: Should 
we borrow the code and use it in a new instance method for this class, or 
should we put the code into a new superclass instance method? 

The general rule of thumb is, if a code segment is replicated more 
than once, then it is a candidate for a new method, especially if it has the 
potential for additional use and its responsibility can be made distinct 
enough to support other methods. The method displayNewData : seems 
to fit the criteria. It seems reasonable that displaying a collection in the 
text widget is a task that other methods may need to do. Also its task is 
quite distinct. Still, it’s a matter of style. At the risk of adding even more 
methods to our “hold” list, we will add the method to our superclass and 
change the superclass fileln method to call it. 


Modifying Our Superclass to Meet Our Weeds 

As we have discovered, sometimes the requirements of a subclass can 
make it necessary to modify the superclass. This situation is usually the 
result of a decision to make a code segment into a separate, more ge¬ 
neric method. Such modifications help to make the superclass more effi¬ 
cient and better able to serve its subclasses. Quite often, you will find 
that changes of this kind result from the fact that at the time you devel¬ 
oped the superclass, you did not envision it as a superclass. Fortunately, 
you are working in Smalltalk, and changes of this type are easy to imple¬ 
ment. So let’s take advantage of this environment’s flexibility and create 
a new superclass method. Here then is the new method (remember, this 
is a PlotWindow instance method: 
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di spl ayNewData: aCollection 

"Add a collection to the end of data's display" 

|appts dates | 

data setstring: String new. 

data insertAndShow: data getLastPosition value: aCollection. 

The only thing left to do in the superclass is to remove the code seg¬ 
ment from the fileln method and replace it with a call to the new method. 
Here is the modified fileln method: 

fileln: widget clientData: ignore callData: callData 
"Use a platform file dialog to prompt 
user for filename to read. Open a filestream and 
read the stream to the data text widget" 

| path file | 

path := CwFi1eSelectionPrompter new 
title: 'File In Data'; 
searchMask: '*.dat'; 
prompt 

path is nil ifTrue:[ A ni1]. 
file := CfsReadFi1eStream open: path, 
self displayNewData: file contents, 
file close. 

self newData: data getString. 

Back to the Subclass and Methods on Hold 

Returning to work on the BusynessWindow class, let’s tackle the method 
we have had on hold the longest, datesSurrounding:. Just as the added 
pieces of a puzzle help to define a missing piece’s shape, size, and color, 
so have our other method definitions been determining the responsibili¬ 
ties and therefore the contents of this method. We know that it must 
answer a collection of dates, and that the first date in the collection will 
be the starting date of the period. From this input we can assume the 
method will create an Ordered Collection of dates, starting with the first 
date of the period. We also know that the period should be flexible, and 
that we need a way to determine the period. 

The period seems like a user preference, and so we will allow the 
user to set the period from the Plot menu’s Options submenu. This in 
turns calls for an easy way for a menu callback to set the period, which 
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points out the need for a new instance variable. Add a new instance 
variable to the class definition and call it period. 

We can now work on the method. The method will use the period, 
stored in the instance variable period, to determine the size of the col¬ 
lection it will answer. We can imagine a period of a week or a month, so 
our method will start by supporting these periods. What we need to know 
for each period is its start date and its length, which we must determine 
using the date passed as an argument. 

From our exploration in Chapter 7 we know we can add and subtract 
dates. So if we subtract the starting date’s index from the provided date’s 
index, we end up with the number of days between the two. Actually, the 
starting date’s index will always be 1, since it will always be the first 
date in the period. The given date’s index will be dependent on the period. 

Once we have the starting date, we simply create a collection by add¬ 
ing 1 to each successive date. So for each period, we need to know the 
number of days in the period and the method required to parse the ar¬ 
gument date. We have enough information to create this critical method; 
here is the code: 

datesSurrounding: aDate 

" Answer a collection of dates starting with 
first date of period including aDate" 

| day dates noOfDays symbol | 

period = #Week ifTrue: [ symbol := #daylndex. noOfDays := 7]. 

period = #Month ifTrue: [ 
symbol := #dayOfMonth. 

noOfDays := Date daysInMonthlndex: aDate monthlndex 
forYear:aDate year. 

]. 

symbol isNil ifTrue: [ A ni1 ]. 

day := aDate subtractDays: ((aDate perform: symbol) - 
1 max: 0). 

dates := OrderedCol1ection new. 

dates addLast: day. 

1 to: noOfDays - 1 do: [:i | dates addLast: (day addDays: i) ]. 

A dates 

As we discussed, the method parses the passed date, iterates over a 
loop the size of the period, adding each date of the period to a collection, 
and then answers the collection. We have defined the week and month 
periods; we leave additional periods to your creativity. 
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We have modified our setup requirements, so we need to modify our 
setup method. We will override the superclass method. 

setup 

"Override superclass setUp and append my needs" 
super setUp. 

" set our own defaults" 
period := #Week. 
factor := 30. 
barWidth : : = 19. 
barSpacing :=5. 

"Add me to the application framework only if ac is set" 
ac not Nil ifTrue: [ 

ac addApplication: self type: #BusynessChart. 
ac application: self has InterestInType: #Calendar. 
self resetActivate]. 

First we call the superclass method to make sure everything is initial¬ 
ized, then we add our own initialization. We override the options de¬ 
fault, so that our initial chart window will display all the plots for one 
week, our period default. Next we add ourselves to the application frame¬ 
work after ensuring the framework has been initialized. 


Adding the Class to the Application Framework 

You may be asking yourself, why do we add ourselves here? Isn’t that 
supposed to be handled in the ApplicationController launch method? 
Our framework does call for the class to be initialized there. 

But this class is a special case in that it needs to be part of the framework 
for activate, events, and to make requests, but not for opening and closing. 
We want users to open and close this class at their discretion. That way they 
can view the period plot when they want and close it when it is not needed. 
As stated earlier, this will require one of the existing applications to control 
the BusynessWindow application, probably from a menu choice. 

The most likely candidate for starting the chart is the Appointment 
Book, so we will add an item to its Appointment menu to do this. The 
standard way of adding a class to the application framework results in 
all windows opening and closing together, so we need a way to circum¬ 
vent this. We can do so by having the AppointmentBookWindow class 
create our plot class instance and pass it the Application Controller in¬ 
stance to use. Once started, the Plot application adds itself to the appli- 
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cation framework, declares its interest in the CalendarWindow event, 
and participates in the activate event structure, thus the code in setUp. 

Conversely when the Plot application closes, it removes itself as an 
application and from the activate structure. Well override the super¬ 
class method closing and add the extra tasks. Here is the method: 

closing 

"Clean up then have superclass clean up 
before closing" 
ac not Nil ifTrue: [ 
self removeActivate. 

ac removeApplicationType: ' BUSYNESSCHART'1. 
self displayNewData: String new. 
super closing. 

This time we call the superclass method after we have performed our 
specific tasks. This order will ensure that the widgets will not be de¬ 
stroyed before we have finished with him. We also check to make sure 
an ac has been defined before trying to send the framework messages. 
Finally, the close method we copied earlier will do nothing now, so it 
looks like this: 

cl ose 

"Do nothing " 

Adding the Request Method 

Moving on, we have yet to add the method to the AppointmentBook- 
Window that will answer the number of appointments for each date in a 
collection, so we will do that now (and in the process temporarily empty 
our “hold” list). 

This AppointmentBookWindow instance method will accept a collec¬ 
tion and then ask its apptbook for the size of each appointment in the 
collection. We have already defined a method in the AppointmentBook 
class that answers a collection of appointments for a date, so we simply 
need to ask the resulting collection for its size, eliminating the need to 
create a new AppointmentBook method. 
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Here is the code for this method: 

numberOfAppointmentsIn: aCollection 

"answer the number of appointments for 
each date in a collection" 

A aCollection collect: [:d | (apptBook appointmentsAt: d) size]. 

Using the collect message we easily iterate through the dates and set 
the sizes for the appointments. Another plus for Smalltalk. 

While we’re in this method, let’s modify the Appointments menu and 
create the resulting callback method. To include the menu item and its 
separator, add the following code segment to the end of the existing method: 

item := form2 

createSeparator: ' sep ' 
argB1ock: nil. 
item manageChi1d . 
item := form2 

createPushButton: 'Display Appointments Plot' 
a rg B1ock : nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #displayPlot:clientData:cal 1 Data : 
clientData : nil. 
item manageChi1d. 

Last but not least, we need the callback method for the menu. Here is 
that method’s code: 

displayPlot: widget clientData: ignore callData: alsolgnore 
"Display the plot window by creating 
a new one and passing it the ac to work with" 

I app I 

app := BusynessWindow new. 
app controller: ac. 
app open. 
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Displaying the Plot 

With the data gathering and application framework methods out of the 
way, we can concentrate on the display methods. The display will look 
the same as PlotWindow’s, except we will use the color scale described 
above. The first display method we’ll work on will be the method that 
sets the correct color for the plot to use. We will call this method setBusy- 
ColorFor:. We have decided to make this a separate method to aid in 
changing both the scale and colors used. Here is the method: 

setBusyColorFor: value 

"set the appropriate color for the value " 

| color | 

"set colors if not set " 

notBusy isNil ifTrue: [self lookupColor: 'green'], 
busy isNil ifTrue: [ self lookupColor: 'yellow']. 
veryBusy isNil ifTrue: [self lookupColor: 'red']. 

value < 3 ifTrue: [ color : = notBusy]. 
value > 5 ifTrue: [ color : = veryBusy]. 
color isNil ifTrue: [color := busy]. 
barGC setforeground: color. 

As you can see, we have created the need for three more instance 
variables, notBusy, busy, and veryBusy. The use of the instance vari¬ 
ables means we have to look up the colors only once. Add the new in¬ 
stance variables, then add the new method. 

The next method to work on is the method that actually plots the 
appointments. For this method we will copy and override the superclass 
method horizontalBar:. To this method we have to add only the code to 
get the correct color, using our recently added method. Add this code at 
the beginning of the do loop. We will display the entire method at the 
end of this section. 

Finally, we want to change one aspect of the PlotWindow class. 
Whereas that class’ newData: method essentially ignores zero values, 
we want days with no appointments to show up as blank bars. If we just 
allow them to be ignored, we’ll end up with bars only for the days on 
which there are any appointments, and these bars won’t line up cor¬ 
rectly with the days to which they correspond. Copy the newData: method 
from PlotWindow and change it as shown below (the line that is changed 
is in bold): 
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newData: a String 

"Accept the user input, and redraw the chart with 
this data. Answer true. 

| input token | 

input := ReadStream on: aString 
plotData := OrderedCol1ection new. 

[input a t E n d] 
whileFalse: [ 
token := inputNextWord. 
token > -1 

ffTrue: [plotData addLast: token asNumber]]. 
self lewPlot. 

A true. 


Testing the New Application 

We are ready to give the new application a smoke test. Execute Applica- 
tionControiler launch, then select the Display Appointments Plot option 
from the Appointments menu of the AppointmentBook application. The 
Busyness Window will display, and the appointments will be plotted, all 
for the current w r eek. You may want to add some appointments to see 
how things work. 

The test looks good, but it would be nice if the user could see the plot 
without having to set the window each time. What we need is for the plot 
to be displayed within the confines of the existing window. All we need 
to do is determine the window’s width and recalculate the bar width 
based on the number of bars and bar spacing so that all bars are drawn 
within the window. Here is the auto-sizing code segment that you can 
add, following the set color code above: 

barWidth := (win height - (theData size * barSpacing))//theData size. 

Test it again. Much better, but something is still missing. Perhaps if 
we added a frame to each bar and made the bar gauges. This requires 
us to draw an unfilled rectangle before drawing the bar in another color. 
Here is the method, in its completed form: 

horizontalBar: theData 

"Draw a horizontal bar plot of the data, an 
ordered collection of integers." 

| x y win | 



IBM SMALLTALK 


312 


x := y:= 0. 

win := drawArea window. 

win clearWindow. 
theData do: [rvalue | 

barGC setForeground: (self lookupColor: 'grey80'). 
barWidth := (win height - (theData size * barSpacing)) // 
theData size, 
wi n 

drawRectangle: barGC 
x: x 

y: y 

width: (win width - 10) 

height: barWidth. 

self setBusyColorFor: value. 

wi n 

fi11Rectangle: barGC 
x: x 

y: y 

width: (factor * value) 
height: barWidth. 
y := y + barWidth+ barSpacing. 

]. 

Notice that because we have set the width of the frame rectangle to 
the window’s width, the gauge will shrink and grow with the window. 
We have also created a ten-pixel gap between the window’s edge and 
the edge of the gauge. The color we chose is grey80, but you may find 
another one you like better. Before we run another test let’s add our new 
code to the verticalBar: method. It is basically the same formula and 
code except we will use the height of the window instead of the width. 
Here is the complete method: 

verticalBar: theData 

"Draw a vertical bar plot of the data, an 
ordered collection of integers." 

| x y win result| 
x : = 0. 

y : = drawArea height - 5. 



CHAPTER 11: A GRAPHING APPLIC A T I 0 N 


313 


win := drawArea window. 

win clearWindow. 
theData do: [:value | 

barWidth := (win height - (theData size * barSpacing)) // theData 
s i 2 : e . 

barGC set Foreground: (self lookupColor: 0grey80'). 
wi n 

drawRectangle: barGC 
x: x 

y: y 

width: barWidth 

height: (win height - 10) negated, 
self setBusyColorFor: value, 
wi n 

fi11Rectangle: barGC 
x: x 

y: y 

width: barWidth 

height: (value * factor) negated, 
x := x +barWidth + barSpacing. 


We have a couple of last-minute tasks to perform that have to do with 
changing the Plot menu so it reflects the new application. In place of the 
colors option, we will put a period option and provide two choices: Week 
and Month. Here is the modified plotMenu: method: 

plotMenu: meriuBar 

"create the Plot menu and its Options and Color submenus" 

| mainForm optionForm colorForm main option color item | 

mainForm := menuBar createPul1downMenu: 'main' 
a r g B1o c k: nil. 


main :=menuBar createCascadeButton: 'Plot' 
argBlock: [:w| w subMenuId: mainForm ]. 
main manageChild. 
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item := main Form 

createPushButton: 'Erase' 
argBlock: ni1. 
item mnemonic:$E. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #clearPlot:clientData:callData: 
clientData: nil. 
itern manageChi1d. 

ftern := mainForm 

createPushButton: 'Redo Plot' 
argBlock: nil. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #redrawPlot:cl tentData:cal 1 Data: 
clientData: nil. 
item manageChi Id. 

item : = mainForm 

createSeparator: 'sep' 

argBlock: [:w | w separatorType: XmSINGLELINE]. 
item manageChild. 

item := mainForm 

createPushButton: 'Horizontal Bar' 
argBlock: ni1. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #setHorizontal:clientData:callData: 
clientData: nil. 
item manageChild. 

item := mainForm 

createPushButton: ’Vertical Bar’ 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #s e t V e r tic a 1:clientData:callData: 
clientData: nil. 
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item manageChi1d. 

item := mainForm 

createSeparator: 'sep' 

argBlock: [:w | w separatorType: XmSINGLELINE]. 
item manageChi1d. 

"Create the option Menu" 

optionForm := mainForm createPul1downMenu: 'option' 
argB'ock: nil. 

option :=mainForm createCascadeButton: 'Options' 
argBlock: [:w| w subMenuId: optionForm ]. 
option manageChild. 

item := optionForm 

createPushButton: 'Stretch Factor' 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #factor:clientData:callData: 
client Data: nil. 
itern manageChi1d . 

item := optionForm 

createPushButton: 'Bar Width' 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #barWidth:clientData:callData: 
clientData: nil. 
item manageChild. 

item := optionForm 

createPushButton: 'Bar Spacing' 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #barSpacing:clientData:callData: 
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clientData : nil. 
item manageChild. 

"Create the Option menu Color submenu" 

colorForm := optionForm createPul1downMenu: 'color' 
argB1ock: nil. 

color :=optionForm createCascadeButton: 'Period' 
argBlock: [:w| w subMenuId: colorForm ]. 
color manageChild. 

item := colorForm 

createPushButton: 'Week' 
argBlock: nil. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: //change Period:clientData:cal 1 Data : 
clientData: #Week. 
itern manageChi1d . 

item := colorForm 

createPushButton: 'Month' 
argBlock: ni1. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: //change Peri od : cl 1 entData : cal 1 Data : 
clientData: //Month, 
item manageChild. 


"Add last menu item to Plot Menu" 

item := mainForm 

createSeparator: 'sep' 

argBlock: [:w | w separator Type: XmSINGLELINE]. 
item manageChild. 
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item := main Form 

createPushButton: 'Restore Defaults ' 
argBlock: nil. 

item addCal1 back: XmNactivateCal1 back 
receiver: self 

selector: #resetDefaults: eld entData : ca IliData : 
clientData : nil. 
item iianageChi 1 d . 

We have created the need for a new method called changePeriod:. 
This method will put the correct symbol, passed to it as clientData, into 
the period instance variable. It will then redraw the plot based on the 
current date: 

changePeriod: aShell clientData: clientData callData: callData 
"Process the Period menu callback." 
period := clientData . 
self currentDate. 

The required current date is obtained from the method currentDate , 
which we will define now. This method will make a request of the calen¬ 
dar application for the current date, which, as you may have guessed, 
we still have to define. Here is the currentDate method: 

currentDate 

"request the currentDate through AC" 
ac request: #currentDate from: ^Calendar. 

Add the following method as a CalendarWindow Instance method: 
currentDate 

"answer my calendar's current date" 

A self dateSelected: calendar day printstring. 

Finally, we need to update setUp to call our new method so that when 
the plot is started it will display the calendar’s current date. Add a mes¬ 
sage send to the instance method currentDate to the end of the setUp 
method within the confines of the ijTrue: block, since we do not want 
this method called if the ac is undefined. 
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The Final Test 

Test the application once more. Try the new features. Everything seems 
to work fine. We have successfully taken a newly created application 
and integrated it with our existing application framework and the 
SimplePIM application. In the next chapter we will use what we learn 
about text to enhance this application even more. In the meantime, take 
a look at the next section for some ideas on additional improvements. 

Some Things to Work Oi 

Here are some ideas for enhancing the application we just finished: 

1. The user may want to view other periods, such as a quarter. 

2o Add the auto-size capability to the superclass. 

3. While auto-sizing is nice, there are times users may want to con¬ 
trol the window themselves. Add an Auto Size menu option that 
toggles this state. Create it using the check box style of toggle 
button. 

4o We removed the Plot application from the close event structure of 
the application framework because we wanted to leave the view¬ 
ing of the plot window to the user’s discretion. One side effect of 
this decision is that when the SimplePIM application is shut down 
the Plot window remains open, and vice-versa. The user would 
like this changed. 
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In this chapter, we will look at the key classes involved in manipulat¬ 
ing text on the screen of an IBM Smalltalk application. Text is graphical, 
in a sense, because each character, symbol, and space is composed of a 
collection of bits. Without ignoring the fact that text is a bit-mapped 
image on-screen, this chapter will focus on text as a collection of char¬ 
acters that has meaning in some context. We’ll begin this chapter with 
an overview of how text is displayed, represented, and manipulated in 
IBM Smalltalk. Then we’ll look at the five primary classes that play some 
role in the world of Smalltalk text. As we discuss each class, we will 
point out important methods and describe the overall role of the class in 
the process of text management. 

Mild the Text in Smalltalk 

Most of the text-related work in IBM Smalltalk is handled by the CwText 
class. This class contains the text field widget which can support single- 
or multi-line text. This all-purpose widget is used for most text-entry 
operations. It has properties which let you set the widget’s word wrap, 
editability, and tab size. A CwText object supports all Edit menu functions. 

Users wanting to edit existing text in a CwText follow the select-then- 
operate paradigm. In other words, they first select the text on which 
they wish to perform some editing operation and then invoke the opera¬ 
tion, usually by selecting it from a menu but possibly by other means (for 
example, typing to replace selected text rather than first cutting it by 
means of a menu selection). 

Let’s look specifically look at methods in the class CwText that handle 
five activities: 


■ Modifying a CwText widget’s current contents 

m Scrolling the widget’s contents to show a designated portion of 
the text 

m Selecting and deselecting text in the widget 

■ Highlighting text in the widget 

■ Setting and getting special CwText states 
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Methods for Modifying Text 

The class CwText defines two methods for adding text to the end of the 
contents of one of its instances: insert-.value: and insertAndShow-.value:. 
Each takes a position as a first and second argument of a string to place 
in the first argument. A position is defined as an integer representing a 
zero-based offset from the top of the widget’s text contents. The differ¬ 
ence is that the second method scrolls the widget so that the inserted 
text is visible. 

Using these two methods in conjunction with the getLastPosition 
method, which answers the last position of the text in the widget will 
allow you to append text to the end of the widget’s text; the same as 
nextPutAll: does for Streams and the Transcript. For example: 

text insertAndShow: text getLastPosition value: 'Put me at the end'. 

The method replace-.toPos-.value : is used to replace or overwrite ex¬ 
isting text. It expects a beginning position, end position, and a string. 
For example, if the current contents of a text widget were “I need re¬ 
placing and soon,” then the following code would change the widget’s 
contents to “I need replacing and now”: 

text replace: (text getLastPosition - 4) toPos: text getLastPosition 
value: 'now' 


Methods for Scrolling Text 

A text-based application might want to alter the scrolling status of a text 
pane’s contents, aside from the user’s direct manipulation of the pane’s 
built-in scroll bars. 

In addition to the insert AndShow-.value: method described above, there 
are two other methods which help with scrolling the widget to specific 
text. To scroll to a specific location in the widget, use the showPosition: 
method, which also takes a position. To scroll to the end of the document 
you would combine getLastPosition with this method: 


text showPosition: text getLastPosition 
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You can also scroll a position to the top of the widget’s visible text 
area with the method setTopCharacter: and a position. 

The getTopCharacter answers the first visible character in the Text 
widget. You could use this method to set a bookmark in the text that can 
be returned to after another scrolling operation. 

Use the scroll: method to scroll the text in the widget a number of 
lines up or down. This method takes an integer representing the num¬ 
ber of lines to scroll—up if positive and down if negative. 

Methods Belated to Text Selection 

There are two types of selection in a CwText. The obvious one involves 
selecting ancl highlighting one or more characters in the pane’s con¬ 
tents. The less obvious selection, called the gap selection, arises when 
no characters have been selected. In that case, the selection refers to 
the position of the I-beam cursor in the CwText indicating where the 
next character typed will be placed. 

The method setSelection: can be used to set a selection. The method 
expects a point. The point’s x value is the beginning position and the y value 
is the ending position of the text to be selected. 

Use one of these methods to edit selected text in a CwText: 


s getSelection returns the text encompassed by the current selection, 
or nil if no text is selected 

h getSelectionPosition answers a point, if any, with an x and y value 


Highlighting Text 

The CwText widget has a method which allows us to set the text to an 
extended and, on some platforms, secondary extended highlight. The 
method setHighlight-.mode: takes as its first argument a point. Yes, you 
guessed it, the point’s x is the start of the highlighted position, and its y 
is the ending position. The second argument is a constant. Use 
XmHIGHLIGHTNORMAL for normal selection, XmHIGHLIGHTSELECTED 
for a highlighted selection (usually reversed), or XmHIGHLIGHT- 
SECONDARYSELECTED to highlight a secondary (inactive) selection on 
platforms which support a secondary selection. 
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Setting Special CwText Attributes 

The class CwText provides support for word-wrapping and a read-only 
text mode. You can change the word-wrapping state of a text widget 
with the method wordwrap: and the state can be tested by wordwrap. 
For both methods, TRUE indicates word-wrapping is on, and FALSE off. 

The methods editable: and editable set and get the state of the wid¬ 
gets editability, with a TRUE indicating that the widget can be edited 
and a FALSE that it is read-only. Both states can be modified on-the-fly. 

The tab-spacing size can be modified with tabSpacing: and tested with 
tabSpacing. The methods work with an integer indicating the number of 
character spaces to use for a tab. 

Tie Role of Foots 

The text world is heavily dependent on some Common Graphics classes, 
particularly those that deal with fonts. In this section we will explore 
these classes. We will learn how to list, set, and use fonts. We will also 
work with text as a graphic object within a C w I) r a wing Ar e a, making 
further use of the sample window we created in Chapter 10. 

IBM Smalltalk’s font system, like the other elements of the Common 
Graphics subsystem we have studied, is based on the X Windows Xlib 
graphic operations. In particular, fonts follow the X11R4 standard (for 
scalable fonts, the X11R5 standards). Consult the appropriate standards 
documentation for details on fonts. 

When you think about fonts you are usually most concerned with the 
basic look of the character set, called its font family. But fonts vary widely 
within each family; they can differ in point size, pixel size, spacing, slant, 
and even blackness, to name only a few. For this reason fonts are some¬ 
what complex. IBM Smalltalk tries hard to remove much of this com¬ 
plexity by breaking the concept of a font and its individual character 
set’s characteristics into separate objects. 

The classes we will be discussing are all Common Graphics subsystem 
classes. Although they are similar to the ones we discussed in Chapter 
10, these classes focus on font storage and manipulation. Here is a list of 
the classes: 
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n CgFont (font) 
m CgFontStmct (structure) 
m CgFontProp (property) 

■ CgCharStruct (character structure) 
m CgLogicalFontDescription (description) 
m CgTextltem (text) 


How Font Classes Interact 

A quick study of the interaction of these classes finds that the CgFont 
class is in the center of the action, with the other classes responsible for 
supporting data. An instance of CgFont is composed of a CgFontStmct, 
which is itself composed of a CgFontProp and a collection of CgCharStruct 
(one for each character in the font). 

The two remaining classes are not directly involved in the font object 
composition, but instead support font operations. The CgLogicalFont¬ 
Description class is involved in specifying and parsing font names, while 
CgTextltem is used to draw multiple text strings by the CgDrawable 
method drawText:x:y:items :. 

Keeping this interaction in mind, let’s look at each of these classes in 
a little more detail. 


The Class CgFont 

The CgFont class, a subclass of the CgID class, represents an instance of 
a loaded font of a given size and style. As we discussed above, a CgFont 
instance is the center of a font object composition. Once a font is loaded, 
it is an instance of this class which is expected by a CgGC and used by 
the CgDrawable text drawing operations. The most commonly used public 
methods for this class are queryFont , which answers a CgFontStmct, 
and unloadFont, which unloads a font, freeing up all its resources. 

The class method default allows one access to the default font which is 
preloaded by the system and should not be freed with the unloadFont method. 
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You most be careful when unloading fonts. It has been our experience that 
unloading the default font will result In a debug message that says "handle not 
understood" whenever you open a new system window or on occasion experience a 
system crash. You will also not be able to file out code. We know of no way to work 
around this issue except to exit IBM Smalltalk and start over. 


The Class CgFontStruct 

The CgFontStruct class describes a specific CgFont instance’s font char¬ 
acteristics. The class is responsible for maintaining information about a 
font instance, including the number of characters in the font, font height 
and average character width, the ascender and descender height, the 
dimensions of each character in the font, and whether the font is 
monospace or proportional. 

The CgFont object can be thought of as a handle to operating system 
resource, whereas the CgFontStruct is a more detailed description of a 
font useful for performing calculations based on text width or height (for 
example, aligning text in a drawing). Some noteworthy instance meth¬ 
ods include: 

m font , which answers the linked CgFont. 

m name, which answers the font’s name. 

m textWidth:, which answers the width in pixels of the provided text 
string. 

■ perChar, which answers an array of CgCharStructs, 

m numChars, the number of characters in the font. 

■ ascent , which answers the height in pixels of the font ascender. The 
ascender is the upper portion of a font character. This method re¬ 
turns the highest ascender of all the font’s characters. 

h descent , which answers the height in pixels of the font descender. 
The descender is the lower portion of a font character. This method 
returns the lowest descender of all the font’s characters. 

m numChars, the number of characters in the font. 

h height, which answers the height of the font (ascender + descender). 

This class also has a class method default which answers the default 
system font. 
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The Class CgFontProp 

The class CgFontProp is another font description object which includes 
the font’s name. This class helps to compose a CgFontStruct. It is re¬ 
sponsible for storing the font’s XLFD or X logical Font description con¬ 
vention name. We’ll discuss the XLFD convention later when we discuss 
CgLogicalFontDescription. Direct access to this class is quite uncom¬ 
mon. You would normally gain access through the CgFontStruct name 
method described above. 


The Class CgCharStruct 

While the CgFontStruct describes the font’s characteristics as a whole, 
CgCharStruct is responsible for describing a single font character’s char¬ 
acteristics. Instances of this class are normally stored in a collection 
kept by the CgFontStruct class. In fact, the CgFontStruct instance method 
perChar answers such a collection. The information provided by this 
class is useful in operations such as word wrapping or text justification. 

The methods of interest for this class are: 

■ ascent , which answers in pixels the individual character’s ascender, 
the upper portion of the character 

n descent , which answers in pixels the individual character’s descender, 
the lower portion of the character 

m width , which answers the number of pixels to advance to the begin¬ 
ning of the next character 


The Class CgLogicalFontDescription 

Although not part of a font object’s composition, CgLogicalFontDescription 
still plays a vital role in the font process. Its main responsibility is to 
parse an XLFD convention string in order to match it to a font. 

The X Logical Font Description (XLFD) convention consists of 14 fields. 
Each field is a set of characters separated by a hyphen, which repre¬ 
sents a particular font characteristic, such as family name. This conven¬ 
tion allows for the use of wildcards in any field to aid in the search of 
fonts. It also supports both scalable and nonscalable fonts. 

For an example of a XLFD convention name, look at Table 12-1. 
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Table 12-1. X Logical Font Description for Sample l\Same String 



FIELD NAME 

VALUE 

EXAMPLE 

adobe 

Font foundry 

X-registered 

vendor 

adobe, bitstream, 

microsoft 

helvetica 

Family name 

Font family name 

helvetica, times, courier, 

wingdings 

bold 

Weight 

Blackness 

or density 

medium, bold 

i 

Slant 

Vertical posture 

of font characters 

r (roman), i (italic), 

ri (reverse italic) 

normal 

Set_width_name 

Width of font 

characters 

normal, condensed, 

narrow, double wide 

sans serif 

Add-style-name 

Additional information 

(often blank) 

serif, sans serif, informal, 

decorated 

0 

Pixel_size 

Font vertical height in 

pixels 

8,10,12,... (0 indicates 

scalable font) 

0 

Point_size 

Font vertical height in 

1/1 Oths of 1/72 of an inch 

(24 points = 240) 120,140,180, 

240, 360 (0 indicates 

scalable font) 

100 

Resolution_X 

Horizontal resolution in 

dots per inch (dpi) 

75,100 

100 

Resolution_Y 

Vertical resolution in dpi 

75,100 

P 

Spacing 

Font spacing 

p (proportional), m 
(monospace), c (character 

cell) 

0 

Average-width 

Average width used to 
calculate monospaced 

and character cell fonts 

to determine the 

characters per line 

50, 60, 70,... 

(0 indicates scalable font) 

iso8859-1 

Charset_registry/ 

encoding 

X-registered name 

indicates coding 

authority 

iso8859-1 


Table 12-1 shows us that our sample XLFD name is for a scalable font 
because there are zeros in the pixel size, point size, and average width 
fields. A nonscalable font would look like this: 
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adobe -helvetica-bold-i-normal-sans serif-12-120-75-75-p-70-iso8859-l" 

These fields are filled in with amounts specifying a particular font. As 
we’ll see later, this distinction is important. 

The instance methods, as you may have guessed, allow you to set or 
get parts of an XLFD name. Those of most interest are the three fields 
which differentiate a scalable and nonscalable font: point: and point , 
pixel: and pixel , and averageWidth: and averageWidth. 

We can use these methods to convert a scalable XLFD, in this case our 
first example above, to a non-scalable XLFD with this code: 

| fontName description | 
fontName := 

' - adobe-helvetica-bold-i-normal - sans serif-0-0-100-100-p-0-iso8859-1' . 
description := CgLogicalFontDescription name: fontName. 
description 

points: ' 240'; 
pixels:: ' * ' ; 
averageWidth: ' *' . 
description name 

This takes a font name string, turns it into a description, then ma¬ 
nipulates the description with a point size and some wildcards, and an¬ 
swers a new description name. The result would be like this: 

"-helvetica-bold-i-normal - sans serif-*-240-100-100-p-*-iso8859-1" 

This description is created by sending an XLFD convention string to 
the class method name: and retrieved via the instance method name. We 
can use the resulting description to load a 24-point Helvetica bold font. 
The search and loading processes, including the use of wildcards, will 
be covered later. 

As you can see from our examples, the XLFD convention allows you 
the ability to specify a font from a string name. It is important to note 
that the description object does not directly point to a CgFont object, nor 
is it directly involved in the font loading or unloading process. It is pro¬ 
vided as a convenient way to manipulate the XLFD convention string. 
You could, if so inclined, create your own string, though probably not 
quite as easily. 
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The Class CgTextltem 

The last class on our list is the CgTextltem class. Like the previous one, 
this class is not actually a font object composition class. Its only role is to 
serve as a data structure for the CgOrawable method drawText:x:y:items :. 
This class has instance variables for each of these data structures: fields, 
characters, string, delta, integer, and font (which is a CgFont object). 

CgTextltem is interesting because it demonstrates the power of IBM 
Smalltalk. Rather than create an array within an array with these ob¬ 
jects in it, just to fit the needs of this method, IBM chose to create a 
separate object. This approach is often overlooked in favor of creating 
increasingly complex objects and arrays. However, this second object 
has some advantages. Not only can you control access to the object more 
directly, but the individual elements of the class are more easily accessed 
because you can use specific methods, rather than a generic and ob¬ 
scure indexing process. The resulting code is easier to write and main¬ 
tain because it avoids the necessity of a complex set of nested loops just 
to manipulate the elements of the class. We’ll see an example of this 
method and class later in this chapter. 

In the next section well learn to manipulate the fonts, then take what 
we’ve learned and do some experimenting. 

Using Fonts to Create Test 

Now that we have explored the classes which make up a font and learned 
about the XLFD convention, we are ready to plunge into loading and 
working with fonts. Fonts are an external operating system resource. 
They can be quite large and require additional resource space so it is 
customary to load fonts only as required, and release font resources and 
unload the font when it is no longer needed. 

In addition, most environments have a large number of fonts avail¬ 
able, so it can be a hassle just to find the right font to load. It should be 
noted that the primary reason for the complexity of the XLFD conven¬ 
tion is the complexity of the fonts themselves. 



CHAPTER 12: THE TEXT WORLD 


329 


The Process of Using Fonts 

The class which participates in the start of the font-loading process is 
CgDisplajo This class has instance methods for searching the available 
fonts and loading a font or font structure. The font, after loading, is 
usually handed over to a CgGC instance, which (you may recall from 
Chapter 10) is the graphics context. The GC font is then used by a 
CgDrawable subclass instance to draw text. Finally, a font is released, 
or freed, by a message to the font itself. This process is simplified in the 
steps found in Table 12-2. 


Table 12-2. Steps for Using a Font 



CLASS 


METHODS 


1. Search for available fonts. CgDisplay 

2. Load resulting font(s) into memory. CgDisplay 


3. Assign font(s) to a graphic context. CgGC 

4. Perform a drawing operation. CgDrawable subclass 


5. Free font(s) from memory. 


CgFosit, CgFontStruct 


listFonts:maxriames: 

loadFont:, 

loadQueryFont: 

setFont: 

drawString:..., 

drawImageString:..., 

drawText:.... 

unloadFont 

freeFont 


Some Examples 

Let’s look at a few examples of interactively dealing with these objects 
so that we can get a clear understanding of their relationships. 

You can follow along with these examples, if you like. Type the com¬ 
mands into the Transcript or a Workspace and execute or display them. 
They can also be found in the file chapl2.wsp, in the chapl2 folder on 
the disk accompanying this book. Also, we will again be drawing on the 
upper-left hand corner, so make sure you have clear area to see the 
results of the examples. 

The first thing we will do is follow the steps outlined above to use a font: 

|names font gc | 
names := CgDisplay default 
1istFonts: '*' 

maxnames: 3. "Answers a collection of names" 
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font := CgDisplay default loadFont: (names at:3)."Pick one" 
gc := CgWindow default 
createGC: None 
values: nil. 

gc setFont: font. "Requires a font not a name or struct" 

CgWindow default 

drawstring: gc 
x: 10 
y: 100 

string: 'Look at me I am a font’, 
font unloadFont. 
gc freeGC. 

You can also skip the search and use a string constant for the font 
name, such as the one we experimented with earlier. You can’t be sure 
which fonts are available so the previous code segment is probably safer: 

| name font gc | 

name := '-adobe-helvetica-bold-i-normal-sans serif-*-240-100-100-p- 
* - iso8859-1'. 

font := CgDisplay default loadFont: name, 
gc := CgWindow default 
createGC: None 
values: nil. 

gc setFont: font. "Requires a font not a name or struct" 

CgWindow default 

drawString: gc 
x: 10 
y: 100 

string: 'Look at me I am another font', 
font unloadFont. 
gc freeGC. 

You’ve heard about it, we’ve discussed it, and even analyzed it. Now 
let’s see how the drawText: method actually works. Here it is: 

|names fontl font2 font3 iteml item2 item3 gc | 
names := CgDisplay default 
listFonts: '*' 

maxnames: 3. "Answers a collection of names" 
fontl := CgDisplay default loadFont: (names at:l). 
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font2 := CgDisplay default loadFont: (names at:2). 

font3 := CgDisplay default loadFont: (names at:3). 

gc := CgWindow default 
createGC: None 
values: nil. 

iteml := CgTextltem chars: 'Still ' delta: 0 font: fontl. 

item2 := CgTextltem chars: 'even ' delta: 0 font: font2. 

item3 := CgTextltem chars: 'more fonts ' delta: 0 font: font3. 

CgWindow default 

drawText: gc 
x: 10 
y: 100 

items: (Array with: iteml with: item2 with: item3). 
fontl unload r ont. 
font2 unload r ont. 
fon13 unloadront. 
gc freeGC. 

Well, we found another way to use the UstFontsimaxnames: method. 
As you can see, the code loads three fonts, then builds three CgTextltems, 
uses the items as arguments to the drawText: method, and finally, like a 
good code segment should, releases all unnecessary resources. 

In this example we separated the words with spaces, but we could 
have chosen instead to set the delta, which is the horizontal offset from 
the previous item. The font is optional. If not set, the graphic context’s 
font is used. You should also have noted that the methods to set the 
CgTextltem are class methods. 

An alternative to this method would be to create three GCs and assign 
a font to each one, then perform three drawStrings. You probably agree 
that this method is easier. Of course if you wanted three different color 
strings you’d have to set a different forecolor for each GC and then draw 
each string. 

We’ll end our trek into the world of text by combining what we learned 
in Chapter 10 with what we have been working with in this chapter. For 
this example within the sample window, we will create three drawn fig¬ 
ures of different colors and label them with three fonts: 
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| shell drawingArea drawable values gc 
names fontl font2 font3 iteml item2 item3 points | 

shell := CwTopLevelShel1 

createApplicationShel1 : 'Font Example' 
argBlock: nil. 
drawlngArea := shel1 

createDrawingArea: 'draw' 
argBlock: [:w | w width: 200; height: 200]. 
drawingArea manageChild. 
shell realizeWidget. 

values := CgGCValues new 
lineWidth: 2. 

drawable := drawingArea window, 
gc := drawable 

createGC: GCLineWidth 
values: values. 

"Find three fonts" 
names := CgDisplay default 
listFonts: '*' 

maxnames: 3. "Answers a collection of names" 
fontl := CgDisplay default loadFont: (names at:l). 

font2 := CgDisplay default loadFont: (names at:2). 

font3 := CgDisplay default loadFont: (names at:3). 

gc := CgWindow default 
createGC: None 
values: nil. 

iteml := CgTextltem chars: 'Still ' delta: 0 font: fontl. 
item2 := CgTextltem chars: 'even ' delta: 0 font: font2. 

item3 := CgTextltem chars: 'more fonts ' delta: 0 font: font3. 

"Draw figures " 

gc setForeground: 12 "blue". 

points := Array with: 10@10 with: 10@60 with: 80@35. 
drawable fi11 Polygon: gc 
points: points 
shape: Convex 
mode: CoordModeOrigin. 







gc setForeground: 10. "green 


drawable fil1 Rectangle: gc 
x: 10 
y: 100 

width: 50 
height: 50. 

gc setForeground: 9 . "Red 
drawable fill Arc: gc 
x: 100 
y: 10 

width: 60 
height:60 
anglel: 0 
angle2: 360*64. 

"Now label them" 
gc setForeground: 0. 
gc setFont: fontl. 
drawable drawstring: gc 
x: 12 
y: 40 

string: 'Triangle'. 

gc setFont: font2. 
drawable drawstring: gc 
x: 115 
y: 40 

string: 'Circle'. 

gc setFont: font3. 
drawable drawString: gc 
x: 15 
y: 125 

string: 'Square ' . 

fontl unloadFont. 
font2 unloadFont. 
font3 unloadFont. 
gc freeGC. 
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Although longer than the others, this example should not have any 
code which surprises you except the fillArc: method, which draws an 
arc using two angles measured V 64 of a degree—thus the 360° 64 for a 
circle. The first angle is measured counter clockwise (CCW) from 3 o’clock. 
Two arc modes are available: ArcChord, which draws a chord, and 
ArcPieSlice, which draws a circle with a chord missing from it. 

In the next chapter we will put our newly acquired knowledge to work 
by adding labels to the chart created in Chapter 11. 



CHAPTER 



In this chapter we use the Smalltalk text and font classes and methods 
we discussed in Chapter 12. We also extend the usefulness and function¬ 
ality of the chart we built in Chapter 11. 

Project Overview 

A frequent use of text in business is in labeling charts and data. The 
project in this chapter builds on the Busyness Chart we created earlier. 
This chart was designed to allow you to view how busy your schedule is 
in a given period. We will extend this chart by labeling weekday names 
and each day’s number of appointments. The user will be able to select 
the font for the chart text on-the-fly and, to make things a little more 
challenging, the font selection will result in the text being resized to fit 
the graphic bars. We’ll build the extended Busyness Chart and then re¬ 
place the current Busyness Chart. Figure 13-1 shows the chart after it’s 
been modified. 


Plot 


c of Sunday January 8,1995 


0 

Sunday 

0 

Monday 

0 

Tuesday 

0 

Wednesday 

0 

Thursday 

0 

Friday 

0 

Saturday 


Busyness Chart created by the project in this chapter 
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Designing the Project 

The major part of this project will be creating a subclass of the 
BusynessWindow class created earlier. The new class will replace its 
superclass and be opened by the AppointmentBookWindow class. 


Statement of Purpose 

This new chart extends the functionality of its superclasses by support¬ 
ing labeling and font selection. The selection of fonts is made using the 
standard IBM Smalltalk font prompter dialog supported by the 
CwFontPrompter class. The chart’s graphic busyness bars, which rep¬ 
resent a single day’s schedule, are labeled with the selected font. Two 
labels are placed on each bar, one indicating the number of appoint¬ 
ments represented by the bar and the other the weekday name of the 
bar. The location of the labels depend on the bar’s orientation, either 
vertical or horizontal. 

The size (width and length) of the bar is determined automatically by the 
size of the window and spacing between bars. Likewise, the number of text 
characters is determined by the size of each bar. This is accomplished by 
drawing either the full weekday name or an appropriate abbreviation. 

The existing chart contains a text widget, inherited from its super¬ 
class, which displays the number of appointments for the given period. 
This text widget is unnecessary, since the individual bars display this 
information. Also, the Edit menu which corresponds to this text widget 
is removed, since it no longer serves any useful purpose. 

Finally, we automate the chart so all changes are viewed immediately 
without further user intervention. This includes selections for font, bar spac¬ 
ing size, bar orientation (horizontal or vertical), and the chart period (weekly 
or monthly). We call this extended chart the ExtendedBusynessWindow. 


General Approach 

We need to subclass the BusynessWindow class. This provides us with a 
window, a graphics widget to draw in, the methods for drawing both 
horizontal and vertical bars, and the methods for updating and coloring 
these bars according to the busyness of the daily schedule depicted by 
the bar. This is all good news and represents the expediency of reusing 
code. We s im ply copy or override the methods as required to make them 
function the way we want. 
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In so doing, however, we inherit things we do not want to utilize—in 
this case, a text widget and all its associated functionality. Fortunately, 
we can take advantage of a widget’s characteristics. Instead of having to 
create a new window without the text widget and having to override 
numerous methods associated with the widget, we simply hide the wid¬ 
get by not mapping it. Then all the operations which require the text 
widget can still be performed, but remain hidden from the user. 

From here we have only to add any new methods required to support 
font selection and test the resulting chart window. 


Knowledge Needed 

An ExtendedBusynessWindow object needs to keep track of one piece 
of information in addition to those already tracked by its superclasses. 
This information can be stored as an instance variable. The variable is 
font, the selected font or default font if no selection has been made 


Building the Project 

Building this project requires six steps. The order of the steps is unim¬ 
portant, but dividing up our work makes it possible to get a prototype up 
and working quickly and then modify its various behavioral characteris¬ 
tics individually. The steps we take are as follows (in the order in which 
we discuss them): 

1. Create the new class with the font instance variable. 

2. Copy or override superclass methods. 

3. Add new interaction methods. 

4. Test the new Chart with the SimplePIM application. 

5. Add font-modification capability to the chart. 

6. Add methods to interact with the SimplePIM applications to auto¬ 
mate the chart. 
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Creating the New Class 

We begin constructing this project by building the ExtexidedBusyness- 
Window class. To create this class, find BusynessWixidow in a Loaded 
Applications Browser under the SimplePIM application, and subclass it 
using the Subclass of Selected Class option under the Add option of the 
pop-up menu. Enter the name as “ExtendedBusynessWindow” in the 
prompter and choose Subclass from the resulting dialog. Add an instance 
variable called font to the template displayed in the source text widget 
and save it. Your template should look like this: 

BusynessWindow subclass: #ExtendedBusynessWindow 
instanceVariableNames: 'font' 
classVariableNames: ' ' 
poolDictionaries : ' ' 


Overriding Our Superclasses 

With our new class constructed, our next step is to provide it with its 
unique functionality. We begin by overriding superclass methods. We 
usually override the superclass by calling the superclass method before 
or after we have added some code which modifies the method’s opera¬ 
tion. However, we can also override the superclass by copying an exist¬ 
ing method in its entirety and modifying some of its code. As you may have 
guessed, the former approach is a more desired means of overriding a su¬ 
perclass, but sometimes, as we will see, the latter approach is the only way 
to accomplish a task. For our purposes we will need to do both. 

Disabling the Text Widget 

We remove the text widget from the chart window by disabling and 
hiding it. You’ll recall widgets are only displayed when they are real¬ 
ized. Prior to realizing a widget, you need to manage and map it. An 
unmanaged widget does not participate in geometric management and 
an unmapped widget does not display. However, the widget itself does 
exist and will respond to messages sent to it. 

The PlotWindow method addText: creates and manages the text wid¬ 
get called data. We need to override this method and unmanage and 
unmap the text widget before it is realized. To do so, we create a new 
method called addText: with the following code: 
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addText: aForm 

"Add an unmanaged and unmapped 
text widget to me" 
super addText: aForm. 
data unmanageChi1d. 
data unmapWidget. 

This method allows the superclass to create a managed text widget. 
Then we override the management of the widget with unmanageChild 
and unmapWidget messages. Now the widget will be invisible to the user. 

Well, not quite yet. The PlotWindow addDrawArea: method attaches 
the graphics widget draivArea to the invisible text widget. This results 
in a large space in the chart which cannot be drawn in. Not at all what 
we are looking for, so we need to override this method as well and force 
it to attach the drawArea to the left of the form, rather than to the text 
widget. Here is the overriding method: 

addDrawArea: aForm 

"Add a drawing area widget to me. Change the attachment of the 
draw area so it attaches to the left of the form, not the data 
area, which is no longerused. " 
super addDrawArea: aForm. 
drawArea setValuesBlock: [:w | w 

1 ef tAttachment: XmATTACFIFORM; leftOffset: 3]. 

Once again, we let the superclass method do its worst and have our 
overriding method clean things up. Note that we provided for a 3-pixel 
offset from the edge of the form to make the display more pleasing to the 
eye. Now that any trace of the text widget is gone, the user has no way of 
knowing it even exists. 

Next, we need to disable the Edit menu. We can’t do this by overriding 
the method that places the Edit menu because we have part of a Catch-22 
working against us. If we call the superclass method and then hide the 
menu, the user will see the menu bar flash as the window is drawn. Bad 
form and ugly to boot. But if we call the superclass method after our 
code, it will simply add the Edit menu because nobody told it not to do 
so. This is an example of a case where completely replacing the method 
is the only way to accomplish our objective. We’ll do this by copying the 
PlotWindow addmenuBar: method and removing the line which calls 
the Edit menu. 
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This seems a good time to tell you about an easy way to copy methods. 
First, select the PlotWindow class, then the addMenuBar: method. From 
the pop-up menu, select the Mark option, then the Global Mark option. 
You have now marked the method for selection. We could have added 
additional methods to our selection with the Extend Mark option but we 
only need this one right now. Select the ExtendedBusynessWindow class 
and once again select Mark from the pop-up menu. This time select Copy 
Marked, which you will find is no longer shaded. The method marked is 
copied to the selected class. That’s all there is to it. All that’s left to do is 
remove or comment out the offending line from the copy of addmenuBar: 

self dataMenu: menuBar. 

The text widget and Edit menu are now disabled. Next, we’ll focus on 
labeling the chart. 

Labeling the Chart 

To label the chart we need to override the BusynessWindow horizontalBar: 
and verticalBar: methods. We also need to initialize out font instance vari¬ 
able with a CgFont. We’ll do this by overriding the PlotWindow open method. 

Before we can work with the labels, we need a font, so let’s use the 
default font for the display. We need the font set before the widgets are 
realized, so we will set the font before calling the superclass open method. 
Create a new open method for the ExtendedBusynessWindow class and 
include the following code: 

open 

"set font before window opens" 

font :=CgDisplay default defaultFont. 

super open. 

The code to set the font is exactly as discussed in the previous chapter. 
Before we discuss the changes to the two bar methods, let’s copy them 
from the superclass. Use the same technique as before, except use the 
Extend Mark option for the second method. When you’ve marked both 
methods, copy them into the ExtendedBusynessWindow class exactly 
as you did before. 

We’ll start with the horizontalBar : method, then take what we learn 
and apply it to the verticalBar : method. Let’s review the operation of the 
horizontalBar: method. Here is the entire method as it looks before any 
code changes: 
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horizontalBar: theData 

"Draw a horizontal bar plot of the data, an 
ordered collection of integers." 

| x y win) 

x := y:= 0. 

win := drawArea window. 

win cl earWindow. 

theData do: [rvalue | 

barGC set Foreground: (self lookupColor: 'grey80'). 

barWidth := (win height - (theData size * barSpacirig)) // 
theData size. 

wi n 

drawRectangle: barGC 
x: x 

y: y 

width: (win width - 10) 

height: oarWidth. 

self setBusyColor For: value. 

wi n 

fill Fiectangl e: barGC 
x: x 

y: y 

width;: (factor * value) 
height: barWidth. 
y := y + barWidth+ barSpacing. 

3u 

As you’ll recall, this method loops, drawing two rectangles per pass, one 
empty and one filled with a color determined by supplied data. Both bars 
are drawn using the CgDrawable method drawRectangle:x:y:width:height:, 
which requires a CgGC to draw with. As we learned in the previous chapter, 
we will also be using a CgDrawable method which also requires a CgGC for 
drawing the text strings. This method is called dr aw String :x:y ’.string:. In 
addition to a CgGC, it requires a String and two integers representing the x 
and y locations of where to start drawing the string. 

The first thing we need is the string to draw. To hard-code this data 
into the method, we create a static array called “days,” containing strings 
that represent the names of the days of the week, and create an index 
into the array called “day.” Here’s the code phrase to use: 
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days := #('Sunday' 'Monday' 'Tuesday' 'Wednesday' 'Thursday' 

'Friday' ' Saturday' ) . 

day := 1. 

Don’t worry about where to add this code to the method, we will present 
the entire method later. 

Now for the hard part, centering the drawn text in the bar. We start 
with the weekday name label which we choose to draw on the right end 
of each bar. For this we must rely on a model of the task. See Figure 13-2. 

We know the barWidth , since this is one of the variables already used 
by the method to draw the two bars. You may recall that we can deter¬ 
mine the average text height by asking the font structure, CgFontStruct, 
for it. Therefore, to calculate the exact center we simply subtract the 
text height from barWidth, which leaves the number representing the 
space left over. By dividing this number by 2, we get the offset above and 
below the text. We now have the y position for the string. 

But wait, we forgot something. Characters are drawn according to 
their base line, not their center. So the y location for the 5 above should 
be at the bottom of the S, rather than the center, and our word should be 
drawn a little above center. Close but not good enough for our applica¬ 
tion. Do you recall two other characteristics of fonts, namely their as¬ 
cent and descent? Ascent is the measurement from the baseline to the 
top of a character and descent is measured from the baseline to the 
bottom of a character. We don’t care about the descent at this time, but 
the ascent is exactly what we are looking for. If we add the offset of the 
ascent to our calculation above, we can compensate for the text being 
drawn at the baseline. 

We now have a formula for the y location, but what about the x loca¬ 
tion? We only need to reach into our magic bag of methods and find the 
one that tells us the width of a text string. It is again a CgFontStruct 
method appropriately named textWidth:. The method takes a string of 


Bar Top Edge 



Bar Left Edge 


Bar Bottom Edge 

Centering Text on a horizontal bar 
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text and answers the number of pixels required to draw the entire string 
in its font. Aimed with this information, we can proceed to formulate a 
calculation for x. We know that the bars are automatically drawn to fit 
within the draw area size. Therefore, the length of a bar is the same as 
the window minus a known offset. If we subtract the text width from the 
draw area width, minus a small offset, we know exactly where to start 
drawing our text string on the x axis. Here for review is the drawString: 
method with its arguments for the weekday label: 

drawString: barGC 

x: win width - 10 - (gcFontStruct textWidth: (dayName)) 
y: y + (((barWidth - gcFontStruct height) // 2) + gcFontStruct 
ascent) 

string: (dayName). 


Be sure to keep track of the number of parentheses and brackets in the above code ^ 
and the code whi ch follows. The nesting of these characters may be quite deep. 

IBM Smalltalk includes a feature to help with the scope of enclosure characters 
such as brackets and parentheses. Double-click just inside the character (to the 
right of a left character"[("). The area between the character and a matching 
character, if any, will be highlighted. By looking to see which character is matched, you 
can determine whether the scope is correct and, if not, add the appropriate character. 



It is exactly as we discussed (don’t worry about where to add the code 
to the method, as we will present the entire method later). Notice the 
code phrase “win width -10.” We took this straight from the existing 
code’s first bar width calculation. The variable dayName has yet to be 
discussed. For now, it holds the string to draw. 

Now for the second label, the number of appointments, which will be 
located on the left end of each bar. To draw this label we use the same 
formula, except that the x location will be offset from the left side of the 
bar. We choose an arbitrary offset of 5, which, after testing, looks good. 
So here is the left drawString method with its arguments: 


win drawString: barGC 
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x: x + 5 

y: y + (((barWidth - gcFontStruct height) // 2) + 
gcFontStruct ascent) 
string: value printstring]. 

We use the loop’s variable value, which is assigned the current day’s 
number of appointments. All we need to do is make this integer a string 
by utilizing the Object class printstring method. All that’s left to do is set the 
font, fontStruct, and text color. Here is the code segment for this task: 

barGC setFont: font, 
ba rGC 

getGCValues: GCFont 

valuesReturn: (values := CgGCValues new). 
gcFont := values font. 
gcFontStruct := gcFont queryFont. 
barGC set Foreground: (self lookupColor: 'brown'). 

We have selected the color brown here, but feel free to use any color 
you find interesting. 

We are now ready to add all these pieces of code to the existing method. 
Here is the entire method with the code changes in bold: 

horizontalBar: theData 

"Draw a horizontal bar plot of the data, an 
ordered collection of integers. Added font and drawstring 
support" 

| x y win days day gcFont values gcFontStruct dayName| 
x := y:= 5. 

days :=#('Sunday' ’Monday' 'Tuesday' 'Wednesday' 'Thursday' 
'Friday' 'Saturday'), 
day := 1. 

win := drawArea window. 

win clearWindow. 
theData do: [:value | 

barGC set Foreground: (self lookupColor: 'grey80'). 
barWidth := (win height - (theData size * 
barSpacing)) // theData size. 
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wi n 

drawRectangle: barGC 
x: x 

y: y 

width: (win width - 10) 

height: barWidth. 

self setBusyColor For: value. 

wi n 

fi11Rectangle: barGC 
x: x + 1 

y: y + 1 

width: (factor * value) 
height: barWidth - 1. 

dayname := days at: day. 
barGC setFont: font. 
barGC 

getGCVa1ues: GCFont 

valuesReturn: (values := CgGCValues new). 
gcFont := values font. 
gcFontStruct := gcFont queryFont. 
barGC set Foreground: (self lookupColor: 'brown'). 

win drawstring: barGC 

x: win width - 10 - (gcFontStruct textWidth: (dayName)) 
y: y + (((barWidth - gcFontStruct height) // 2) + gcFontStruct 
ascent) 

string: (dayName). 

win drawString: barGC 
x: x + 5 

y: y + (((barWidth - gcFontStruct height) // 2) + gcFontStruct 
ascent) 

string: value printSt ring, 
y := y + barWidth+ barSpacing. 
day := cay + 1. 

day > 7 ifTrue: [day := 1]. "For periods longer than a week" 
barGC set Foreground: (self lookupColor: 'grey80'). 

]• 

The new code fits perfectly into place. The last bit of code added in- 
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crements to our day index variable so it points to the right day name. 
The next line of code resets the index so we can display a month as well 
as a week. As you can see, we really did need to copy this method be¬ 
cause there wasn’t an easy way to modify its behavior with a new over¬ 
riding method. 


The First Test after Remodeling 

Before we move on to the verticalBar: method let’s test the new chart 
and see how it works. To run the test we have to modify one Appointment- 
BookWindow method, displayPlot:clientData:callData:. We need this 
method to launch our new class instead of the BusynessWindow class. 
Simply replace the reference to BusynessWindow with Extended- 
BusynessWindow and save the method. Next, launch the application by 
entering and executing the following: 

Appl1cationControl 1 er launch 

Now select the Display Appointment Plot menu item from the Appoint¬ 
ments menu. The new chart will appear and should look like Figure 13-1, 
although the font may be different depending on the configuration of 
your system. Close the ExtendedBusynessWindow window and quit the 
application. 

Did you notice one of the advantages of subclassing the 
BusynessWindow class? That’s right, we are already hooked into the 
application controller framework, without any additional work on our 
part. Isn’t inheritance wonderful? 


A Bar with a Different Perspective 

With a successful test to fuel our enthusiasm, we can jump right into the 
verticalBar: method. For this method we have to change our perspective 
and look at the horizontal bar calculations turned 90 degrees. Let’s view 
our model again, this time designed for a vertical bar. 

As you can see from Figure 13-3, our first change in perspective is to 
think of the text as being at the top and bottom of the bar. The text width 
now determines how to fit text within the width of a bar, not its length. 
The text height determines the offset of the text from either the top or 
bottom of the bar. 
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Figure 13-3. 


Bar Bottom 

Centering Text on a vertical bar 


With these changes in mind, let’s try to modify the horizontal bar cal¬ 
culations. Here is the code segment from the horizontalBar: method, 
which draws the right-hand label which we’ll convert to draw a top label: 


win drawString: barGC 

x: win width - 10 - (gcFontStruct textWidth: (dayName)) 
y: y + (((barWidth - gcFontStruct height) // 2) + 
gcFontStruct ascent) 
string: (dayName). 

It seems reasonable to assume we can simply swap the x and y calcu¬ 
lations—and indeed we can, with one caveat. We must use the window 
height, not its width, for the y calculation. Let’s look at the new code: 

win drawString: barGC 

x: x h- (( barWidth - (gcFontStruct textWidth: (dayName)))//2) 
y: (win height - 10) + gcFontStruct ascent 

string: (dayName). 

There is one more thing to consider. Can you see what it is? If you said 
the y calculation results in a location above the top of the bar, give your¬ 
self points for being observant. If not, don’t feel too bad. We didn’t catch 
it either before testing it. 

We must now subtract the window height and offset from the current 
y location before adding the ascent. Remember, the y location is set to 
draw the bar from the bottom to the top of the window. So our calcula¬ 
tion must take this fact into consideration, and subtract from y, thus 
moving up the bar, in order to position our string correctly. Here is the 
modified code segment: 
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win drawstring: barGC 

x: x + (( barWidth - (gcFontStruct textWidth: (dayName)))//2) 
y: ( y - (win height - 10)) + gcFontStruct ascent 
string: (dayName). 

The code for the number of appointments’ x labels will be the same. 
The y location simply requires that we move up the bar by the font as¬ 
cent to compensate for the baseline drawing of a character, which keeps 
the label from extending beyond the bottom of the bar. Here is the code 
phrase for this calculation: 

win drawstring: barGC 

x: x + (( barWidth - (gcFontStruct textWidth: (value 
printString)) )//2) 
y: y - gcFontStruct ascent 
string: value printstring. 

This completes the change in perspective. The rest of the code modi¬ 
fications are the same as the horizontal bar. The entire method is pre¬ 
sented below, again with changes in bold: 

verticalBar: theData 

"Draw a vertical bar plot of the data, an 
ordered collection of integers." 

| x y win result day days gcFont values gcFontStruct daySize 
dayName| 
x := 0. 

y := drawArea height - 5. 

days :=#('Sunday' 'Monday' 'Tuesday' 'Wednesday' 'Thursday' 

'Friday' 'Saturday' ). 
day := 1. 

win := drawArea window. 

win clearWindow. 
theData do: [:value | 

barWidth : = (win width - (theData size * barSpacing)) // 
theData size. 

barGC set Foreground: (self 1ookupColor: 'grey80'). 
wi n 

drawRectangle: barGC 
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x: x 

y: y 

width: barWidth 

height: (win height - 10) negated, 
self setBusyColorFor: value, 
wi n 

fi11 Rectangle : ba rGC 
x: x + 1 

y: y 

width: barWidth - 1 

heigh:: (value * factor) negated. 

dayName := days at: day. 
barGC setFont: font, 
ba rGC 

getGCValues: GCFont 

valuesReturn: (values := CgGCValues new). 
gcFont := values font. 
gcFontStruct := gcFont queryFont. 
barGC set Foreground: (self lookupColor: 'brown'). 

win drawstring: barGC 

x: x -- (( barWidth - (gcFontStruct textWidth: 
(dayName)))//2) 

y: ( y - (win height - 10)) + gcFontStruct ascent 
string: (dayName). 

win drawString: barGC 

x: x + (( barWidth - (gcFontStruct textWidth: 

(value printSt ring) ))//2) 
y: y - gcFontStruct ascent 
string: value printstring, 
day : == day + 1. 

day > 7 ifTrue:[ day := 1]. "For periods longer 
than a week" 

x := x +barWidth + barSpacing. 

]. 


As before, the pieces fit nicely into the existing code. 
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Figure 13-4. 


The Extended Busyness chart with vertical bars 


A More Extensive Test 

We are now ready for another test. Bring up the application as we did 
earlier and open an ExtendedBusynessWindow from the Appointment- 
BookWindow appointment’s menu. This time select Vertical Bar from 
the charts Plot menu. Then select a date on the calendar. The resulting 
chart should look the same as the one in Figure 13-4, making allowance 
for the difference in configuration. 

Try extending the width of the window. Notice how the text stays cen¬ 
tered in the bar. Now try shrinking the width and notice the text is still in 
the middle of the bar. If you shrink the window enough, you will notice 
that the text extends beyond the size of the bar and overlaps other text. 
We will remedy this in just a moment. Change the orientation back to 
horizontal and try expanding and shrinking the height of the window. 
Notice again how the text remains in the center. Close the application 
and the window. 


Keeping the Text from Overlapping 

It became apparent in our testing that the current code allows the text 
to overwrite the bars and, as a result, overlap other text. We must also 
consider that we intend to allow the user to select the font. This could 
result in charts which are unreadable at best, and quite ugly at worst. In 
either case we can be assured that our user will not be pleased. There¬ 
fore, we must come up with a way to control the displayed text. 
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One approach might be to restrict the font size the user can select, but 
it would be unfriendly to limit the user’s interaction with the chart. An¬ 
other way is to restrict the number of characters displayed. For example, 
we could abbreviate the weekday names to their first three letters when 
the whole name will not fit in the bar. When this text is too large for the 
bar we could then drop to the first letter of each name. And finally, when 
even one letter is too large to display, we could turn off the label display 
altogether. Likewise, when the bar is too small to display the full height 
of the text, we could turn off the label display. 

Controlling the text requires a few conditional statements. To turn off 
the label display completely we will make the display code conditional. 
So the only thing that remains is determining the test conditions. In the 
case of vertical bars we are concerned with the width of text versus the 
width of the bar. Horizontal bars compare the text width to the length of 
a bar. By relying on the CgFontStruct characteristics, as we did earlier, 
we can keep our code font-independent. 

Enhancing tSie vertical Bar: Method 

Let’s start with the vertical bar code. Test the width of the largest text 
string, “Wednesday,” at index 4 of the day’s array. If this text is wider 
than the bars, we’ll set the size of text to 3; if not, we’ll set the size to - 
1. (Don’t confuse the term “text size” with “text width.” Text size is used 
to determine the number of characters to display. Text width is the amount 
of space required to draw the text.) If the text size of 3 won’t fit, we want 
to use only one character. For this test we first need to determine whether 
we are already at a text size of 3; if so, we need to test if we can fit the 
largest string’s first three characters into the bar width. If not, we re¬ 
duce the text size to 1. Finally, we use the text size to copy the desired 
number of characters from the day name string and assign them to the 
dayName variable. Here’s the code segment that accomplishes this task: 

"Now calculate the day name size to use" 

(gcFontStruct textWidth: (days at: 4)) > barWidth 
ifTrue : [ daySize := 3] 
ifFalse: [daySize := -1]. 
daySize = 3 
IfTrue: [ 

(gcFontStruct textWidth: ((days at: 4) copyFrom: 1 to: 

3)) > barWidth 
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ifTrue: [ daySize:= 1]]. 
dayName := daySize = -1 

ifTrue: [days at: day] 

ifFalse: [ (days at: day) copyFrom: 1 to: daySize]. 

The only thing that remains is to enclose the entire display code seg¬ 
ment, including the code above, into its own conditional test which com¬ 
pares the font text width and height, respectively, to the bar width and 
window height. The code fragment for this conditional test is below: 

(CbarWidth - (gcFontStruct textWidth: ((days at: 4) copyFrom: 1 
to: 1))) > -1) 

and: [ (win height - (gcFontStruct height * 3)) > -1]) 
ifTrue: [ 

The closing bracket of ifTrue: follows the word “printstring” near the 
bottom of the method. In the first line, we compare the two items, bar 
width and text width, by determining whether their difference is zero or 
greater. Next, we check to see if the difference between the window height 
and font height is greater than -1. We multiply the font height by 3 to 
make sure we have enough space for both strings and their offsets. Fi¬ 
nally, we join the two conditions with and:. This says that if both condi¬ 
tions are greater than -1, we display the labels, and if either is less than 
-1 then we do not display any labels. The entire method, with the added 
code in bold, follows: 

verticalBar: theData 

"Draw a vertical bar plot of the data, an 

ordered collection of integers." 

| x y win result day days gcFont values gcFontStruct daySize 
dayName| 

x : = 0. 

y := drawArea height - 5. 

days :=#('Sunday' 'Monday' 'Tuesday' 'Wednesday' 'Thursday' 'Fri¬ 
day ' ' Saturday'). 

day := 1. 

win := drawArea window. 

win clearWindow. 

theData do: [:value | 
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barWidth := (win width - (theData size * barSpacing)) // theData 
size. 

barGC set Foreground: (self lookupColor: 'grey80'). 
wi n 

drawRectangle: barGC 
x: x 

y: y 

width: barWidth 

height: (win height - 10) negated, 
self setBusyColor For: value, 
wi n 

fi11Rectangle: barGC 
x: x + 1 

y: y 

width: barWidth - 1 

height: (value * factor) negated. 

barGC. setFont: font. 
barGC 

getGCValues: GCFont 

valuesReturn: (values := CgGCValues new). 
gcFont := values font. 
gcFontStruct := gcFont queryFont. 
barGC set Foreground: (self lookupColor: 'brown'). 

(((barWidth - (gcFontStruct textWidth: ((days at: 4) 
copy From: 1 to: 1))) > -1) 

and: [ (win height - (gcFontStruct height * 3)) > -1]) 
ifTrue: [ 

"Now calculate the day name size to use" 

(gcFontStruct textWidth: (days at: 4)) > barWidth 
ifTrue: [ daySize := 3] 
ifFalse: [daySize := -1]. 
daySize = 3 
ifTrue: [ 

(gcFontStruct textWidth: ((days at: 4) copyFrom: 1 to: 3)) > 
barWidth 

ifTrue: [ daySize:= 1]]. 
dayName := daySize = -1 

ifTrue: [days at: day] 

ifFalse: [ (days at: day) copyFrom: 1 to: daySize]. 
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win drawString: barGC 

x: x + (( barWidth - (gcFontStruct textWidth: 

(dayName )))//!) 

y: ( y - (win height - 10)) + gcFontStruct ascent 
string: (dayName). 

win drawString: barGC 

x: x + (( barWidth - (gcFontStruct textWidth: 

(value printstring)))//2) 
y: y - gcFontStruct ascent 
string: value printstring], 
day := day + 1. 

day > 7 ifTrue:[ day := 1]. "For periods longer 
than a week" 

x := x +barWidth + barSpacing. 

J, 


A Quick Test to Check Our Progress 

Before we make the changes to the horizontalBar: method, let’s test the 
chart window and see whether our enhancements are working. Launch 
the application, open a chart window, choose the vertical bar orienta¬ 
tion, and expand and shrink the width of the window. Is the number of 
characters displayed altered as expected? Do the labels stop displaying 
when the window is too small to show them? Try the same test by short¬ 
ening and lengthening the window. 


Enhancing the horizontalBar: Method 

Our next task is to incorporate the changes we made to the verticalBar: 
method into the horizontalBar: method. Our conditional testing com¬ 
pares window width against the text width of the number of characters 
we are working with, plus an offset that represents spacing large enough 
to maintain aesthetically pleasing spaces. (You may find that you prefer 
a larger or smaller offset. If so, simply set the offset multiplier to the 
desired amount.) The result of each test is to assign a day size. The 
following represents the code segment we need: 
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win width <= ((gcFontStruct textWidth: (days at: 4)) + 

((gcFontStruct textWidth: value printstring) * 3)) 
ifFalse: [daySize := -1] 
ifTrue: [ daySize := 3]. 
daySize = 3 

ifTrue: [ 

win width <= ((gcFontStruct textWidth: 
((days at: 4) copyFrom: 1 to: 3)) + 
((gcFontStruct textWidth: value 
printstring) *3)) 

ifTrue: [daySize := 1]]. 

dayName := daySize = -1 

ifTrue: [days at: day] 

ifFalse: [(days at: day) copyFrom: 1 to: daySize]. 

As you can see, the basic code is the same. Only the test has been 
changed. As before, we need an encompassing conditional test to deter¬ 
mine if we would be displaying any labels. This code uses the window 
width phrase we just developed with a test comparing bar width to font 
height. The code is below: 

(barWidth > gcFontStruct height 

and: ".win width > ((gcFontStruct textWidth: ((days at: 4) 
copyFrom: 1 to: 1)) * 2.0)]) 
ifTrue: [ 

Again, we multiply the width by 2 to reserve space for two characters. 
You can test the horizontal bar code if you like before moving on. In the next 
section we will enable the user to select the font used to display the labels. 


Font Selection Made Easy 

With the string drawing methods complete, we can now focus on font 
selection. Fortunately, IBM Smalltalk has a built-in widget for this op¬ 
eration, CwFontPrompter. A CwFontPrompter supports a standard font 
dialog which allows you to choose the family name, weight, style, and 
point size of a selected font. Conveniently, the dialog also displays a string 
of text in the selected font (see Figure 13-5). Accessing the prompter 
could not be easier. You send the class the new and prompter messages. 
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To see an example, enter and execute the following: 

CwFontPrompter new prompt 

The dialog answers nil or a string representing the font in the (XLFD) 
format which was discussed in the previous chapter. Once a font is se¬ 
lected, we’ve only to load it and assign it to the font instance variable. 
We will combine all of this into a single new method called font:dient- 
Data.-callData: which will be called from a menu. The code for this method 
is below: 

font: widget clientData: clientData callData: cal 1 Data 
"Get a font from the user." 

| oldFont| 
oldFont := font. 

font := CwFontPrompter new prompt, 
font notNil 

ifTrue: [ 

font := drawArea display loadFont: font. 
oldFont ~= CgDisplay default defaultFont 

ifTrue: [oldFont unloadFont]. 
self newPlot]. 



f ; iljM An Open CwFontPrompter 





CHAPTER 13: A BUSYNESS INDICATOR 


357 


There are a couple of points to clarify. First, as discussed earlier, any 
font that is loaded must be unloaded in order to free up the resources it 
uses. A font is unloaded by sending the unloadFont message to a CgFont. 

Second, the message newPlot redraws the chart, the same as the Redo 
option in the Plot menu. So, unlike its superclass, this window automati¬ 
cally redraws the chart without any further user intervention. In a later 
section we will extend this “automation” to other Plot menu items. 


You must be careful while unloading fonts. St has been our experience that unloading 
the default font results in a debug message about a handle not being understood 
when you open a new system window or, on occasion, a system crash. Complicating 
the problem is the fact that you will also not be able to file out code. We know of no 
way to work around this issue except to exit IBM Smalltalk. For this reason we have 
added a test that only unloads a font if it is not the default font. 



Adding Font Selection to the Plot Menu 

Connecting up the font selection method to the Plot menu is the next 
thing on our task list. For this operation, we need to copy the superclass 
plotMenu: method and modify it. At this point we have to decide where 
to put the font selection menu item. Rather than create a new menu 
item, we’ll replace an item that is no longer valid. The item in question is 
labeled “Bar Width.” We no longer need this menu option since the bar 
width is determined automatically, so let’s replace it with an item la¬ 
beled “Font. . .” Make this modification to the plotMenu: and change the 
callback selector to call our font selector methodfont:clientData:callData:. 


Automating the Extended Chart 

All that is left to complete our original task list is automate some addi¬ 
tional Plot menu items. Actually, all that needs to be done is to add a call 
to the newPlot method to each item’s callback method. Once again, in¬ 
heritance makes it easy to extend the functionality of our superclasses’ 
methods. We simply call the superclass method before sending the mes¬ 
sage newPlot:. The code for the setHorizontahclientDataicallData and 
setVertical:clientData:callData methods is below: 
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setVertical : widget clientData: clientData cal 1 Data: cal 1 Data 
"Set the plot type to horizontal bar and replot" 
super setVertical: widget clientData: clientData cal 1 Data: cal 1 Data. 
self newPlot. 

setHorizontal : widget clientData: clientData cal 1 Data: cal 1 Data 
"Set the plot type to horizontal bar and replot" 
super setHorizontal : widget clientData: clientData cal 1 Data : call Data . 
self newPlot. 




q We made an arbitrary decision to automate only the options most frequently 

selected by the user. If you like, you can automate the rest of the Plot menu options 
by creating similar new methods for each item's callback method. 


Ready for Final Testing 

One final method before the testing. We will use a printOn: method to 
reduce our extended class’ extended name to three characters, as we’ve 
done for the other application components. Below is the code: 

printOn: aStream 

"Indicate the window type" 
aStream nextPutAll: ’ EBW:’. 
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Smalltalk as a language is unique because everything is in the environ¬ 
ment. Classes, methods, and objects live together in memory as an au¬ 
tonomous, self-reliant community. You can save this community when 
you exit, and re-enter it again to find everything exactly as you left it. It’s 
as if the community is frozen in time while you are gone. We quickly 
grow used to this all-inclusive development environment, and can some¬ 
times forget there is any other way to work. However, we must also 
realize that applications cannot remain confined to memory; they must 
be able to store and retrieve objects outside of Smalltalk. 

This chapter discusses the management of external files in IBM 
Smalltalk. It presents the primary classes and methods you’ll need to 
create, open, close, update, and manipulate the contents of text files on 
your hard disk from within your application. 

The IBM Smalltalk Comion File System 

The most common way of dealing with external storage and retrieval is 
through the use of files, and the IBM Common File System subsystem is 
the set of classes you can turn to for file management. The Common File 
System class names are all prefixed with the letters “Cfs” and consist of 
classes to handle both low-level file and directory management as well 
as a high-level streams interface. 

The Common File System, like the Common Graphics and Common 
Widgets subsystems, is based on a standard. The standard in this case is 
called PQSIX.l, which includes a standard protocol for basic file opera¬ 
tions such as searching directories, managing files and directories, 
unbuffering input and output, and file locking and sharing. The inter¬ 
face provided by IBM Smalltalk shields you from the need to make calls 
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at the operating system level. Error-handling messages are based on a 
subset of the POSIX.l error handling. 

The Common File System also provides complete support for file 
streams protocol based on the existing IBM Smalltalk streams protocol, 
making it possible for you to treat a fde like a stream. In addition, there 
is portable support for platform-specific attributes such as line delimit¬ 
ers, path separators, and file system roots. 

The Anatomy of a File 

Before we look at the way Smalltalk handles files and streams, let’s talk 
about how files are stored on the disk. 

Files use special non-printing (and usually non-displaying) characters 
called control characters to separate or delimit information. These charac¬ 
ters are used to help identify the structure of information, just as punctua¬ 
tion and spaces are used to identify the structure of this sentence and sepa¬ 
rate words and paragraphs. If you took all the spaces out of this sentence, 
the text would become one large unreadable word. With spacing, we are 
able to determine where words begin and end, a process called parsing. 
The placement of control characters in files help to parse file information. 

Consider a standard text file. It uses control character(s) to determine 
the end of each line of text. It can’t use punctuation since sentences may 
actually extend across multiple lines of text. We call this an EOL or “end 
of line.” The end of the text is determined by the EOF or “end of file” 
control character(s). 

Now for a bit of complexity: not all disk operating systems use the 
same characters for each of these functions. For example, UNIX-based 
systems use a single control character called a line feed (LF) to delimit 
text lines, while DOS systems use a combination of control characters 
called a carriage return (CR) and line feed (LF), usually written as “CR/ 
LF.” (By the way, these names are taken from the predecessor of the 
computer, the typewriter, where a “carriage return” meant that the car¬ 
riage—the part of the typewriter on which paper rests—was pushed to 
the right, a process called “returning.” A “line feed” was the process of 
feeding the paper up a line.) 

Not all files, of course, are used to store textual data. Sometimes, as is 
the case with an address book, information is stored not according to 
spacing, but according to its structure. Each address in our book is 
thought to be a record and each data item, such as name, address, state, 
and ZIP code, are considered fields. Each of these structure elements 
require a delimiter character as well. These characters are usually at 
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the desecration of the application, but some standard formats do exist 
and you may have heard them referred to as comma-delimited or tab- 
delimited files. What this means is that data items are separated by com¬ 
mas or (if delta contains commas) by tabs. Each record is delimited by 
the disk operating system’s EOL character(s). 


Preparing to Use the Common Fife System 

Portability between platform-specific file systems has become a hot is¬ 
sue. To promote portability, IBM Smalltalk provides constants for speci¬ 
fying values such as access modes, file creation and share modes, and 
file error numbers and messages. These constants are stored in the pool 
dictionary CfsConstants. Any class that references these constants must 
list CfsConstants as a pool dictionary. You may also find the pool dictio¬ 
nary CltdConstants useful, which is not a part of the Common File Sys¬ 
tem but does provide access to constants associated with the names and 
values of various unprintable ASCII characters, including control char¬ 
acters and, most importantly, platform-dependent line delimiters, as dis¬ 
cussed above. 

File Streams 

The most common way of dealing with files in Smalltalk is to use file 
streams. Unlike some other dialects, IBM Smalltalk provides a separate 
class hierarchy for file streams, primarily to promote cross-platform file 
management; and manipulation support. Compatibility with streams is 
maintained by supporting the streams protocol. So the method nextPutAll: 
is supported by FileStream classes, but is refined to accept only charac¬ 
ters or bytes. In addition to the streams protocol, FileStream classes 
have their own protocol for handling files with methods such as 
openEmpty which would have no meaning to streams classes. 

Streams (and therefore file streams) are high-level mechanisms for 
manipulating objects as a serial, collection, or stream of data—hence 
the name. Because the streams are high-level, the programmer does not 
have to be concerned with the mechanics of how an object is stored (i.e., 
with memory locations, storage allocation size, boundary conditions, or 
conversion of the object from a hierarchical to a flat data format). Addi¬ 
tionally, file streams isolate the programmer from the complexities of 
records. In other words, streams and file streams make it more conve¬ 
nient to deal with objects as data. 
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Tiie FiieStream Classes 

The CfsFileStream class hierarchy looks like this: 

Cfs Fi1eStream 

CfsReadStream 

CfsReadWriteFileStream 
CfsWriteFi1eStream 

The responsibilities for these classes are as follows: 


CfsFileStream Class 


CfsReadFileStream 

CfsWriteFileStream 

CfsReadWriteStream 


This is an abstract class which implements 
the protocol common to all of its subclasses 
and includes support for creation of streams 
on open files as well as opening files and 
streams 

This class supports the input of data only 
This class supports the output of data only 
This class supports both the input and out¬ 
put of data 


The classes share a common protocol so we look at them as a group, 
pointing out differences as we encounter them. The operations of file 
streams fall into three main categories: opening files, processing files, 
and closing files. Not all file streams need to open and close files. Like 
streams, file streams can operate on existing collections, in this case 
files. Another type of object, called a CfsFileDescriptor, is involved in the 
pre-opening and post-closing of a file before and after stream operations. 
This class and its counterparts, which we will cover in a later section, are 
responsible for accessing files, including setting file access modes. 


Opening File Streams 

Before you can input or output data, you must have a source or destina¬ 
tion for it. In the case of file streams, the source or destination would be 
a file. The CfsFileStream classes provide methods for opening and clos¬ 
ing files. These methods answer a file stream and expect a filename. 
They handle all file access mode configurations for you. You have only 
two methods to be concerned with, open: and openEmpty:. The latter 
creates or overwrites an existing file and, as you probably reasoned, the 
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CfsReadFileStream class does not respond to this message. Since these 
class methods not only open a physical file, but also create the file stream, 
it is easy and convenient to create them. So to create a file stream for 
reading and writing on a file named “mydata.dat” you would use the 
following code: 

I file | 

(file := CfsTeadWriteFi1eStream open: 'mydata.dat') is CfsError 
ifTrue: [ A self error: file message]. 

This code introduces a new method called isCfsError, which checks 
whether an object is of class CfsError. This will be discussed later along 
with its counterpart the CfsFileDescriptor class. The resulting file vari¬ 
able is either a read-write file stream or a CfsError. A read-write file 
stream is ready for further processing, while CfsError returns an error 
message corresponding to the error encountered. 

One more point about openEmpty: should be made. This method over¬ 
writes an existing file without any warning. It is up to you to verify over¬ 
writing the file with your user before calling this method. We will see an 
example of this later. 


Processing File Streams 

Processing a file stream involves placing objects in the stream, copy¬ 
ing them from a stream, removing them from a stream, or simply search¬ 
ing for objects. Once you have a file stream, you use the streams proto¬ 
col methods for all types of access (just remember that unlike their stream 
complements, they are restricted to character and byte objects). 

You may want to restrict file processing further to one of the two ob¬ 
ject types. The methods isBytes: and isCharacters: are used to set the 
type of object with a Boolean. Corresponding messages isBytes and 
isCharacters allow you to test the current type of object being processed. 
These messages affect the operations of streams protocol messages such 
as contents, next, nextLine, upTo: and upToAll:. 


There are several issues of concern associated with the use of double-byte versus 
single-byte characters on multiple platforms. We highly recommend that you review 
this discussion in the manual before mixing these objects and/or dealing with 
multiple platforms. 
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Different platforms use different line delimiters. By default, the file 
stream operations use the platform’s line delimiter. You can override 
this behavior and set the line delimiter or use a constant representing 
the supported platform delimiters. To set a new line delimiter send the 
message lineDelimiter: plus a constant which is a valid line delimiter. To 
find out what the present delimiter is, send the message UneDelimiter. 


Flushing File Streams 

Simply adding data to a stream does not put the data in the file. To do 
this, you must flush the stream by sending it the message flush. 


Closing File Streams 

Files are a resource. As with all resources it is important to make sure 
you release them when you are done with them. This operation for files 
is called closing. Closing a file allows IBM Smalltalk and the underlying 
platform operating system to finish writing all data and to release all the 
file’s resources. Closing a file stream closes its corresponding file. To 
close a file stream send the message close. 


A Few Examples 

In this section we will play (I mean work) with file streams. Although the 
code is easy, it is still quite functional. We begin with an example of 
writing to, then reading the same file: 

Simplest Example 

"Example 14-1" 

|fi1eRead fileWrite results data| 

"Start by opening a file to write, erasing any existing file" 
(fileWrite := CfsWriteFi1eStream openEmpty: 'mydata.dat') isCfsError 
ifTrue: [ A self error: fileWrite message]. 

"Now write out some data" 

fileWrite nextPutAll: 'Hello out there in file land! I am a 
string' ; c r. 

fileWrite close. "To make sure all data has been written to disk" 
"Read in the file" 
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(fileRead : i= CfsReadFi 1 eStream open: 'mydata.dat') isCfsError 
ifTrue: [ A self error: fileRead message], 
results := fileRead contents. 
fileRead close. 

"Answer the resulting stream's contents" 

A results. 

As you can see, we follow the streams protocol. We use a nextPutAll: 
method to store the data on the file stream, then read the whole file with 
a streams contents protocol message. Notice that we must close the file 
before reading it. As explained above we need to make sure all the data 
has been written to the file and that it has been released by the OS. This 
also ensures that you will not get a locking error when you read the file. 

The next example is a little more complex. This time we write out 
more than one line and type of object, resulting in a string that displays 
each object’s value: 

Multi-Line, multi-Object Example 

"Example 14-2" 

|fi1eRead fileWrite results data| 

"Start by opening a file to write, erasing any existing file" 
(fileWrite := CfsWriteFi1eStream openEmpty: 'mydata2.dat') 
isCfs Error 

ifTrue: [ A self error: fileWrite message]. 

"Now write out some data" 

fileWrite nextPutAll: 'Hello out there in file land I am a 
string' ; c r. 

fileWrite nextPut: 234;cr. 

fileWrite nextPutAll: ' and so am I';cr. 

fileWrite c'ose. "To make sure all data has been written to disk" 

results := ReadWriteStream on: '. 

(fileRead := CfsReadFi1eStream open: 'mydata2.dat') isCfsError 
ifTrue: [ A self error: fileRead message]. 

"Read the data into a stream" 

[fileRead atEnd] whileFalse: [ 
data :== fileRead nextLine. 
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data size > 1 

ifTrue: [ results nextPutAll: data, 
ifFalse: [results nextPutAll: data first aslnteger 
printString , ' , ’ ]. 

]. 

fileRead close. 

"Answer the resulting stream's contents" 

A results contents. 

Notice how we use nextPutAll: for the strings and nextPut: for the 
integer. On the read side we have even more differentiation between the 
two. First, we decide to use a stream to hold our results which we will 
display as a string with the contents message. To display an integer as a 
string, we usually employ the printstring message. But what are the 
other conversions for? Well, it turns out that the nextLine message an¬ 
swers either a string or a byte array, depending on the file stream type, 
characters, or bytes. Because we are in character mode, we get back a 
string. What’s worse is that it is a character in a string, not an integer, so 
we have to convert the string to a character, then convert the character 
back into an integer. 

How could we have avoided this conversion process? Simply, by con¬ 
verting the type of data the file stream handles. The next example ex¬ 
plores this concept, using the methods isBytes: instead of the conversion 
methods. To save space we will focus this time only on the read part: 

Using Type Conversion 

"Example 14-3" 

|fi1eRead fileWrite results data| 
results := ReadWriteStream on: '. 

(fileRead := CfsReadFi1eStream open: 'mydata2.dat') isCfsError 
ifTrue: [ A self error: fileRead message]. 

"Read the data into a stream" 

results nextPutAll: fileRead nextLine,',’. 

fileRead isBytes: true. 

results nextPutAll: fileRead next printstring,','. 
fileRead nextLine. "Read over cr" 
fileRead isBytes: false, 
results nextPutAll: fileRead nextLine,','. 
fileRead close. 

"Answer the resulting stream's contents" 

A results contents. 
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The results are the same as before, except this time the file stream 
code took care of the conversion for us. We changed the structure of the 
method in order to show how the isBytes messages would work. The 
second nextLine is a quick way to read over the “cr”; if we didn’t do this, 
the next line in the subsequent section of code would contain only a “cr,” 
resulting in the last part of the file being skipped. 

A Comma-delimited File Example 

In the next example we explore the issue of field delimiters. When infor¬ 
mation needs to be stored according to its structure, the elements of the 
structure need to be delimited from one another. In this example, we 
create records consisting of name and sex fields. We will display these 
field names and values in the Transcript as we extract them from the 
file. Here is the code: 

"Example 14-4, A Comma - Delimi ted file" 

| fileRead fileWrite delimiter names sexes record fields | 
delimiter := $,. "Set the field delimiter" 

"Start by opening a file to write, erasing any existing file" 
(fileWrite := CfsWri t e Fi1eStream openEmpty: 'mydata3.dat') isCfsError 
ifTrue: [ A self error: fileWrite message]. 

"Create two string arrays of with data" 

names := 'Tom La'^ry Pam Jeanne Roger Alex Martin' substrings, 
sexes := 'male male female female male male male' substrings. 

"Now write out the names and sexes in a delimited record format" 

1 to: names size do: 

[:index | fileWrite 

nextPutAll: (names at: index); 
nextPut: delimiter; 
nextPutAll: (sexes at: index); 
cr; 
f 1 ush 

]. 

fileWrite close. 

(fileRead := CfsReadFf1eStream open: 'mydata3.dat') isCfsError 
ifTrue: [ A self error: fileRead message]. 
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"Display the contents of each comma-delimi ted record" 

[fileRead atEnd] whileFalse: [ 

record := fileRead nextLine. 

fields := record substrings: delimiter. 

Transcript cr; show: 'Name: ';show: (fields at: l);cr. 
Transcript show: 'Sex: '; show: (fields at: 2 ) ;cr. 

"use four spaces for alignment" 

]. 

fileRead close. 

Looking at the code you can see we create two arrays of data, which we 
write out in the form “name,sex.” Notice the use of flush between records; 
this is a common practice when writing records to make sure the record is 
written to the file. In a multi-user application this practice becomes critical 
since it assures that the record is available to others to read. 

On the read side of the code we simply parse each line of the file with 
the substrings: method set to our delimiter. Then we take the results 
and display them in the Transcript. 

Suppose you wanted to store full names in last-name-first format: i.e., 
Kennedy, John F. Using comma-delimited fields would result in: 

Name: Kennedy 
Sex: John F. 

Name: male 

Not at all what we want. Don’t be concerned; that’s the role of tab- 
delimited fields. Instead of breaking the fields at commas they are bro¬ 
ken at tabs. Because we set the delimiter to a variable we have only to 
change the variable’s contents to support a tab-delimited format. We 
leave this as an exercise. 

One significant point is that files are type-dependent and structure- 
dependent, meaning you have to know not only what you wrote out but 
the order in which you wrote it. While you can set and test for the mode 
of a file stream operation, you cannot test for the type of object in a file. 
This is because it is a byte or character rather than an object. We will 
deal with the intricacies of structuring files in our application in Chapter 15. 
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That completes our look at file streams. In the next section we’ll move 
down to the low-level operations performed by file descriptors and di¬ 
rectory descriptors. 

Low-Level File Mechanics 

In the following sections we look at the mechanics of low-level file ac¬ 
cess. We discuss file descriptors, directory descriptors, and other ob¬ 
jects which participate is this subsystem. These classes permit the pro¬ 
grammer to dive deeper into the mechanics of file manipulation and 
management. We look at functions such as searching directories and 
accessing file descriptions, including size modification date, time and 
mode attributes, and file opening modes. 


File Descriptors 

The class CfsFileDescriptor is responsible for all operations relating to 
files. In fact, file streams work with file descriptors as well. The file 
descriptor is a platform-independent handle to an operating system file 
handle. The class is equivalent to a POSIX.l file descriptor and its functions. 

Due to the complexity and flexibility of these objects, much of their 
discussion is beyond the scope of this book. While we will not deal with 
low-level file processing, we will look at opening and closing file de¬ 
scriptors, as well as how they can be mixed with file streams. 

Opening File Descriptors 

There are a number of modes in which a file can be opened. The Com¬ 
mon File System provides constants for the open access modes and flags 
which you will encounter while working with file descriptors. Tables 14- 
1 and 14-2 list these constants and their functions. We have bolded the 
elements of the names to make them easier to recall. 
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Table 14-1. Open Access Modes (Specify) 


MODE MEANING 


ORDONLY Open Read Only. In shared file system this is equivalent to a read¬ 
only lock. Others can access, but you can't write. 

OWRONLY Open Write Only. In shared file systems this is equivalent to a write- 
only lock. Others can not access, only you can write. You cannot 
read. 

ORDWR Open Read and Write. In shared systems this is also a write lock. 

Others cannot access, only you can write or read. 

Table 14-2. Open Flags (Specify Zero or More) 


FLAG NAME PURPOSE 


OAPPEND Open and Append to the file. File offset is set to the end before 
each write. 

OCREAT Open by Creating a new file if one does not already exist. If a file 
does exists, OCREAT does nothing unless OEXCL is also set. 

OEXCL Open is Exclusive, meaning it will fail if OCREAT is set, and file ex¬ 

ists. Otherwise has no effect. 

OTRUNC Open and Truncate file if it exists and if in a write mode. Equivalent 
to file stream message openEmpty:. 

Opening a file descriptor involves providing a filename and file open 
flag to the method opemoflag: The oflag parameter is formed by taking 
one item from Table 14-1, “ored” (using the Boolean OR operator) with 
zero or more items from Table 14-2. Here is an open equivalent to a file 
stream openEmpty 

I fd I 

(fd := CfsFi1eDescriptor 

open: 'mydata3.dat' 

oflag: ORDWR | OCREAT | OTRUNC) isCfsError 
ifTrue: [ A self error: fd message]. 

"Do something with the file" 

As you can see, you have much more flexibility with a file descriptor 
open over file streams. 
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Closing File (Descriptors 

As with file streams, you need to close file descriptors when you are 
done. In fact, the close message you sent to a file stream was relayed to 
the file descriptor used by the file stream. 

You should he careful when working with opened files; on some plat¬ 
forms the number of available operating systems file resources may be 
limited. Failing to close your files properly will eat up these resources, 
which may result in you not being able to open any additional files, even 
those in other applications. This is especially true when debugging file 
processing code. IBM Smalltalk does not close the file automatically for 
you. So if you close a debugger without manually closing the file, it is left 
in an open state and you have no way to access it. 

How can you avoid this? While in the Debugger, access the variable hold¬ 
ing your file descriptor or file stream (you did assign it didn’t you?), inspect 
it, and in the left-hand text area, enter the close message like this: 

self close. 

Your file will be closed and your resources returned. 

Combining File Descriptors end File Streams 

Once you have opened a file descriptor you can resort back to the streams 
protocol by creating a file stream on a file descriptor using the message 
CfsFileStream in the class method on:. You won’t see this method in the 
Common File System application classes because it is actually imple¬ 
mented by the platform specific subapplications. 


Working with Directories 

There are three classes to utilize when working with directories. These 
classes are CfsDirectoryDescriptor, CfsDirectoryEntry, and CfsStat. The 
class CfsDirectoryDescriptor manages the services for creating, delet¬ 
ing, and searching directories. The class CfsDirectoryEntry represents 
the information stored in directory entry for a single file. CfsStat pro¬ 
vides support for accessing directory and file statistical information (size, 
type, modification date and time, and attributes). 

The CfsDirectoryDescriptor class has many useful class methods. The 
methods chdir:, mkdir:, and rmdir: allow you to change the wor kin g di¬ 
rectory, create a directory, and remove a directory, respectively. The 
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methods remove and rename delete and rename files and, on some plat¬ 
forms, rename directories as well. 

The CfsStat class and its subclass CfsDirectoryEntry provide instance 
methods for accessing file statistics and, in the case of the subclass, the 
entry’s filename. A CfsStat contains data on an individual file, while 
CfsDirectoryEntry is normally used in conjunction with the 
CfsDirectoryDescriptor for directory searches. We will discuss these 
classes in turn later. 

Handling Platform Dependencies 

There are some CfsDirectoryDescriptor class methods which can help 
you deal with platform dependencies such as root directories and file 
path separators. These methods are rootDirectories, which answers the 
root (or roots) directories dependent on the platform, and pathseparator- 
String or pathSeparator, which answers a string or character, respec¬ 
tively. Since results vary according to platform, we will let you deter¬ 
mine the results of these methods on your own. 


Statistically Speaking 

As we mentioned earlier, the class CfsStat provides services for query¬ 
ing file statistics. A CfsStat object is usually created by sending the class 
the message stat: and a legitimate fdename. Once you have a CfsStat 
object, you can query it about the last modification time of the repre¬ 
sented file by sending the instance message stMtime, query about the 
size by sending stSize, and query about the file type and mode attributes 
by sending stMode. The method stat: is both a class and an instance 
method. The instance method allows you to change the file on which the 
instance is maintaining statistics, without creating a new stat object. 

The above methods are supported on all platforms. The class sup¬ 
ports other methods (not covered here) that are platform-dependent and 
answer nil if not supported. 
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Searching Directories 

Searching directories can sometimes be a cumbersome task. Instances 
of CfsDirectoryDescriptor can be opened and then searched with the 
standard wildcard characters “$*” and The class method 

opendir:pattern:mode: takes a string representing the directory path, a 
string representing a search pattern (including wildcard characters), and 
a mode composed of the ORing of one or more of the three constants 
listed in Table 14-3. 

Table 14-3. Directory Search Constants 


CONSTANT DESCRIPTION 


FREG matches regular files 

FDIR matches directories 

FSPECIAL matches special files that are neither files nor directories 

Once opened, a directory is searched by reading the entries that match 
the search pattern. Entries are read the same way as streams, with each 
read answering the next entry. 

Three forms of directory reading are supported. The instance method 
readdir: answers a new instance of CfsDirectoryEntry with each read. 
The method readdir: takes an argument of a CFsDirectoryEntry, which 
it fills with each read. The latter method provides better performance 
since the overhead of creating a new CfsDirectoryEntry object is elimi¬ 
nated. Lastly, if all you need are the names of the files searched, use the 
readdirName message, which answers a string containing the filename 
for the next directory entry on each read. The methods all answer nil 
when no more entries matching the pattern are available. When your 
search is complete, be sure to close the directory descriptor with the 
message closedir. 

Once you have a CfsDirectoryEntry object, query with the CfsStat 
messages discussed above, or the dName message, which answers the 
current entry’s filename. 
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Some Examples 

We have covered quite a bit of material, so let’s take a break and look at 
some code examples on what we discussed. The first example shows 
how you can create and query a CfsStat object: 

I f s I 

fs := CfsStat stat: 'mydata2.dat'. 

Transcript cr; 

show: fs stMtime printString;cr; 
show: fs stSize printString;cr; 
show: fs stMode printString;cr. 

We sent the query results to the Transcript so they could be seen. 
Notice that we used printstring, a good method to use since all classes 
know how to respond to it. You may not always get the object in the 
format that you want (for example, instead of a date and time we display 
an array), but you can usually determine the kind of object. 

Our next piece of code deals with a directory search using the readdir: 
instance method. We will search for all “dat” files and include directo¬ 
ries as well as files in our search: 

"Directory search using readdir:" 

| dd de | 

dd := CfsDirectoryDescriptor 
opendir : ' . ' 
pattern: '*.dat' 
mode: FDIR | FREG. 
de := CfsDirectory Entry new. 

[(dd readdir: de) notNil ] whileTrue: [ 

Transcript cr; 

show: de printSt ring; cr; 

show: (de stMtime at: 1) pri ntStri ng, ' ',(de stMtime at: 2) 

printstring; cr; 

show: de dName printstring. 

]. 

dd closedir. 

This time the Transcript displays statistics on the directory entries 
searched. Notice that we loop through the entries until one is nil, at 
which point we break out the loop and close the directory. The code 
shows the steps to searching a directory: 
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1. Open the directory on a directory path and use a search pattern. 

2. Read the directory until all matching entries have been exhausted. 

3. Close the directory. 

Once we have a directory entry we display similar statistical data, just 
as we did with the CfsStat entry. Notice, though, a slight change; we 
broke out the array elements and then displayed them as separate dates 
and times. We used the “.’’string, which on most platforms means the 
current directory. This brings up the point that the search pattern can 
contain platform-specific path characters, but you should be careful us¬ 
ing them. 

We will explore the readdirName method next and this time we will 
search for all files, including directories in our parents’ directory. Here 
is the code: 

| dd filename | 

dd := CfsDirectoryDescriptor 
opendir : ' . . ' 

pattern: "warning may be platform specific" 

mode: FDIR | FREG. 

[(filename := dd readdirName) notNil ] whileTrue: [ 

Transcript cr; show: filename. 

]. 

dd c1osedir. 

The code is very similar to the last segment except we don’t need a 
directory entry. Instead, we get a filename which can be displayed di¬ 
rectly on the Transcript. 

The last two sections of this chapter present two ways to make your 
development life even easier. These techniques are not part of the Com¬ 
mon File System but they do work with files. 

The File Selection Prompter 

We have already had some experience with the CwFileSelectionPrompter 
class in our application code. We will look at it from the perspective of 
providing an interface to file searches. 

First, let’s review the file selection prompter. This is a Common Wid¬ 
get class which displays the platform standard file selector to the user. 
You configure it with four instance methods, searchPath:, searclnMask:, 
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fileName: and title:. The searchPath: method sets the string of the initial 
directory to search, searchMask: sets the file pattern to search, fileName: 
sets the default name to assign, and title: sets the title of the prompter. 
Sound familiar? The file selection prompter is opened with the prompt mes¬ 
sage. Here is an example of this code using the setup of our last example: 

CwFi1eSelectionPrompter new 

title: 'An Example Prompter'; 
searchPath: '..'; 
searchMask: ; 

fileName: 'anyfile.dat'; 
prompt. 


Parsing the Directory Path 

When the user selects a file and clicks OK, the prompter closes and an¬ 
swers a selected filename. When the user selects a file and clicks the OK 
button, the prompter closes and answers the selected filename. From 
this response, parse the directory by reversing the string and then selecting 
upTo: the pathSeparator, then reversing the remaining stream’s contents. 
For example, look at the following code (with added code in bold): 

"File Selection Prompter Example" 

| file aStream | 

file := CwFi1eSelectionPrompter new 
title: 'An Example Prompter'; 
searchPath: '..'; 
searchMask: '*.*'; 
fileName: 'anyfile.dat'; 
prompt. 

((ReadWriteStream on: file reverse) 

upTo: CfsDirectoryDescriptor pathSeparator; 
nextLine) reverse 


That works well, but it is a bit awkward. 
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A New Method 

It turns out that the prompter actually has a class variable that stores 
the last path selected, which it uses as the default path. This class vari¬ 
able is called DefaultSearchPath. If we add a class method to answer 
this path we can save all the reversing above. Here is the method, called 
defaults ear chPath. Install it by adding to the SimplePIM application as 
an extension of the CwFileSelectionPrompter class: 

Defa u1tSearchPath 

"added by WSH to support auto file in" 

A Defa ultSearchPath 
and a new example that uses it: 

CwFileSelectionPrompter new 

title: 'An Example Prompter'; 
searchPath: '..'; 
sea rchMas k: 

fi1eName: 'anyfile.dat'; 
prompt. 

CwFi 1 eS el ect' ; on Prompter defaul tSearchPath. 

As you can see, it is a more straightforward way of finding the path. 
This is the same code we use for the fllemein.st file you have been using 
to load in the chapter code. 

A word of warning. We are modifying a base class and using a private 
variable. Both should raise red flags and remind you that base classes 
can change and so can their variables. We have been careful. By adding 
the code to our application, we keep it from affecting other applications. 
You can also set the method to a new category like “my modifications.” 

Persistent Object Storage 

While we are sometimes forced to store objects in flat files (a subject 
area we cover extensively in the next chapter), the preference is to store 
them as objects. 

The term “persistent objects” refers to the idea of storing objects some¬ 
where other than in the image. As IBM Smalltalk gains popularity (and 
we all know it wall), the need for a direct means of object storage be¬ 
comes more important. 
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IBM Smalltalk offers a set of services which is a compromise to full 
persistent object storage but it is much easier than flat object storage. 
This is the ObjectSwapper with its subclasses ObjectDumper and 
ObjectLoader. These classes make it easy for the programmer to store 
objects in files. The classes are located in the application Swapper. 

ObjectDumper, as you can tell from the name, is the class responsible for 
dumping objects into a file. ObjectLoader retrieves objects from a file. These 
classes provide a considerable amount of flexibility when working with ob¬ 
jects and files, so much so that some of it is beyond the scope of this book. 
We will concentrate on the methods that are easiest to use. 

The ObjectDumper instance method unload-.intoFile: takes an object 
and a filename, and dumps the object into the file. On the other side of 
the coin is ObjectLoader’s instance method loadFromFile: which takes 
only one argument, a filename, and answers the object in the file. 

An Example 

You may be wondering if you can dump more than one object. The an¬ 
swer is yes. You can because collections are objects, so you can put them 
in a collection and dump it, which is exactly what our example does: 

| myCollection 1oadedCol1ection | 

myCollection := OrderedCol1ection with: 'Hello out there' with: 234 with: 
#ByeForNow. 

Transcript cr; show: 'Starting Collection: myCollection printstring. 

ObjectDumper new unload: myCollection intoFile: 'col 1ect.obj' . 

"Now load it back in" 

1oadedCol1ection := ObjectLoader new loadFromFile: 'col 1ect.obj'. 
Transcript cr; show:'Loaded Collection: 1oadedCol1ection printstring. 

Here are the results: 

Starting Collection: OrderedCol1ection('Hel1o out there' 234 #ByeForNow ) 
Loaded Collection: OrderedCol1ection('Hel1o out there' 234 #ByeForNow ) 

As you can see this is easy. There are no files to worry about opening 
and closing, and no concerns about characters or bytes. 
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What's Beyond Object Swapping? 

Why would you need something more than this, you ask? Well, the an¬ 
swer is that you still have to dump and load a fde. Access to objects is not 
as natural as it is in IBMSmalltalk where you don’t need to be concerned 
where an object is stored. Full persistent storage works like a network 
file server: you request a file and the system finds it for you. So it is with 
persistent storage. Although objects are not in memory, you access them 
exactly as if they were. 

For runtime applications you have two choices: fiat object storage, 
such as a relational database, or persistent object storage, such as an 
object database. The former forces the programmer to parse an object 
and store its essential data into a file, then read back in the data and 
create an object. The latter handles storage for you, leaving an object as 
an object. 

In the next chapter we will look into flat storage of objects as part of 
the SimplePIM application and then work a little more with the 
ObjectSwapper. 




Fin m/mm 


In this chapter we’ll work with the classes and methods in IBM Smalltalk 
streams and files, which we discussed in Chapter 14. We will extend the 
AppointmentBook application by providing a means to store and re¬ 
trieve the appointments collection. 

Project Overview 

A frequent use of files in business is to store data. In the past we relied 
on IBM Smalltalk’s image-saving to save the appointment data entered 
by the user. However, an actual application must deal with external data 
storage. In this chapter we extend the AppointmentBookWindow class 
by adding external data storage and retrieval. To accomplish this goal, 
we’ll extend two more classes, AppointmentBook and Appointment. 

We’ll add Save and Retrieve menu items to the AppointmentBookWindow 
Appointment menu which calls the code necessary to store and retrieve 
the appointment data. We will also restrict ourselves to loading and sav¬ 
ing all appointments rather than dealing with them singly. 

The code for this chapter is contained in four files named aptmntcl.st, 
aptmntin.st, appbkcl.st, apptbkin.st, and apptbkwn.st. These files con¬ 
tain Appointment class and instance methods, AppointmentBook class 
and instance methods, and AppointmentBookWindow instance meth¬ 
ods. You can load these files separately as we work, or all at once by 
loading the file filemein.st, which loads the files for you. There are also 
some test files with the extension .apt. You’ll see what to do with these 
files later in the chapter. 

Designing the Project 

The major part of this project stores and retrieves the appointment data 
collection currently stored as an AppointmentBook class variable named 
Appointment. We need to consider exactly how the data should be stored, 
so it can be quickly and easily retrieved. 









IBM SMALLTALK 


382 


The Issues 

One issue of object-oriented development is how to store objects in external 
files. After all, an object is itself composed of objects. You can think of an 
object as if it were a mobile, with the object at the top and its instance 
variable objects hanging below. Each of these objects has its own instance 
variable objects, and so and so on, each layer adding to the complexity of 
the mobile. Our mobile would soon be unmanageable if at some point we 
did not have some objects which did not contain additional objects. Fortu¬ 
nately, we do. They are called primitive objects and include strings, charac¬ 
ters, and Booleans. In order to store an object we need to convert it into 
primitive objects which can then be stored as text or binary data. 

The next issue is how to separate the data so it can be easily parsed 
and rejoined to form the original object. As you will see, this can be quite 
a challenge. 

Finally, we are faced with the mechanics of opening, reading, writing, 
and closing files. The best way to handle these mechanisms depends on 
how you resolve the first two issues. Sometimes you will want to use binary 
transfer methods, which move data as if it were bytes. Other times, string 
and character transfer methods are necessary to store data as text. 


Object Store Thyself 

Mobiles can become unmanageable when they are too complex. On the 
other hand, complexity in objects is easy to manage when you leave the 
management up to the objects themselves. Object storage is made easier 
by having each object handle its own storage. Perhaps the easiest way to 
see this is by working with a collection. Imagine a collection with a String, 
an Integer, a Time, and a Date. Below we have provided the code and its 
displayed result: 

(Array with: 'Hello' with: 2 with: Time now with: Date today) 

('Hello' 2 10:12:28 AM 01/13/95) 

The display results from each item in the array being sent the 
printstring message. Each object handles the message by displaying it¬ 
self the way it wants to be seen. 

IBM Smalltalk follows a convention for simple object storage, which is 
based around the storeOn: method. This method creates an executable 
IBM Smalltalk statement and stores it as a string. Here is an example 
using the above array: 
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| aStream | 

aStream := ReadWriteStream on: String new. 

(Array with: 'Hello' with: 2 with: Time now with: Date today) do: [:i 
| i storeOn: aStream]. 

'Hello' 2((Time basicNew) 


instVa rAt 

1 

put: 

10; 

instVa rAt 

2 

put: 

12; 

instVa rAt 

3 

put: 

28; 

instVa rAt 

4 

put: 

37098 

yourself) 




((Date ba^ 

sicNew) 


instVa rAt 

1 

put: 

13; 

instVarAt 

2 

put: 

1 ; 

instVa rAt 

3 

put: 

1995; 

instVa rAt 

4 

put: 

13; 


yourself)' 


As you can see, each object stores itself in a form from which it can be 
recreated. Notice how the Time and Date objects have stored themselves 
as executable Smalltalk statements, whereas the primitive objects, String 
and Integer, don’t need statements. 

We are not normally interested in an object’s recreation statement 
when storing objects in files. Instead, we want to store the essence of the 
object and it is best if this essence is in the form of text or bytes. What is 
the essence of an object? It is the part of the object which can be parsed 
or separated into smaller, rejoinable pieces. Put another way, it is the 
primitive objects, such as strings or numbers, which make up the object. 
For instance , take the Time object. The essence of Time is its display 
string—e.g., “11:22:33 AM.” These primitive objects are things we can 
easily work with. So the goal of external storage is to find a way to con¬ 
vert the object and its composition objects into primitive objects. 


Keeping Appointments 

With this understanding we are ready to store the objects in our applica¬ 
tion. Recall that appointments are made up of a start time, an end time, 
and an entry. The first two are instances of the Time class and the last is 
a String object. Each of these objects is entered and displayed as a string. 
For storage purposes, we’d like the essence of an appointment to consist 
of three strings. We can use the Appointment displayStartTime and 
displayEndTime to convert the start time and end time to strings. Of 
course, the entry is already a string. 
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We’re almost ready to write our storage method. First, we need to 
determine how to rejoin this strings back into an appointment. You see, 
we can’t just throw a bunch of strings out to a file. We need some way to 
determine where one string begins and another ends. This involves pars¬ 
ing the stored data and looking for clues as to how to break the data up 
into strings of their original size. 

There are two basic approaches to parsing. The first involves the use 
of tokens , or delimiters—such a spaces, tabs, or punctuation marks—to 
separate the data into distinct parts. This is what your mind is doing 
right now as it interprets this chapter’s words, sentences, and paragraphs. 
The other approach requires counting the items of data, and breaking 
the data at predefined locations. For instance, suppose I gave you the 
text, “meetdavenearpinkboatthishour,” and asked you to parse it into 
words. The words of the text are not delimited by spaces and seem to 
overlap. What if I added that each word is exactly four letters long. Now 
parsing the text is easy. You count four letters, break off the word and 
continue counting until you have the message, “meet dave near pink 
boat this hour.” 

As a rule of thumb, you’ll want to use delimiters when dealing with 
text of unknown length and counting when working with data which can 
easily be broken into uniform lengths. Comma- and tab-delimited files 
are an example of the first approach and counting is used by some data¬ 
bases to determine how to separate their records, assuming a standard 
record size. 

Looking at the Appointment data, we see the times are of a fixed size, 
but we still cannot avoid using delimiters. You see, the entry data is not 
a fixed length. In fact, it is free-form text data, the worst kind because of 
its unpredictable size and contents. For a delimiter to be effective, it 
must not be contained in the data it is delimiting. Think what would 
happen if I used a space to delimit the lines of text in this paragraph. 
Because spaces are already used to separate words, you wouldn’t know 
if the spaces were separating words or lines. That’s why the appoint¬ 
ment entry represents a worst-case scenario. The user is free to enter 
any text, so delimiting the appointment data with a tab, carriage return, 
or any visible character is out. We need to find a delimiter which the 
user cannot type. Control characters cannot be used because we already 
ruled out tabs and carriage returns. Therefore, the character repre¬ 
sented by the integer 255, which is invisible but available, must be used 
to delimit text strings. 
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Now that we have delimited the object’s data, we need to consider 
how to delimit the object itself. In other words, how do we know when 
we have finished parsing an object? To delimit an object we’ll use the 
character with a value of 254, which allows us to parse an object and 
separate out its data. 

Enough Design, Let’s Build It 

At last we are ready for some code, and you will find it below: 

storeTo: aStream 

"store object information on aStream separated by del delimiters" 

I de‘ | 

del := (Character value: 255). 
aStream 

next Put:del ; 

nextPutAl1: sel f displayStartTi me; nextPut: del; 
rextPutAl1: self displayEndTi me ; nextPut: del; 
nextPutAl1: entry. 

We use the nextPut: and nextPutAll: Stream methods we discussed in 
the last chapter to store the strings onto the stream. Using this format, 
aStream can be any kind of Stream or FileStream. 

So what about restoration of an appointment? If an object can store 
itself, then can’t an appointment restore itself as well? Does restoration 
need to be handled by an external method? Perhaps it could be handled 
by a class method which creates an appointment, then calls an instance 
method to restore the appointment’s data from the stream. This approach 
maintains the object’s encapsulation by assuring that changes to the 
Appointment class only affect the Appointment class’ methods. We could 
have the AppointmentBook recreate an appointment by utilizing the 
methods we use to create a new appointment. However, each time we 
added or removed an instance variable we would have to change the 
AppointmentBook and Appointment methods. This allows a potential 
for bugs, which we want to avoid at all costs. 

Let’s create a class method called restoreFrom: which expects a stream 
and answers a new restored appointment. This method can be called by 
an external method when an appointment needs to be restored. Of course, 
the work is done by an instance method of the same name and called 
from the class method. The instance method also expects a stream and 
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answers the receiver. It first parses the whole object from the stream, 
then each individual data object. Both methods are listed below, in the 
order discussed: 

restoreFrom: aStream 

"answer a new appt created from 

data in a stream. Assumes proper delimiters 

for data. See storeTo: for details" 

A super new restoreFrom: aStream. 

restoreFrom: aStream 

"restore object data from a stream separated by del delimiters" 

| del objDel objectData | 

del := (Character value: 255). 

objDel := (Character value: 254). 

objectData := aStream upTo: objDel. "get all obect data" 
objectData : = objectData substrings: del. "now parse 
each data item and assign" 

self start: (objectData at: 1) end: (objectData at: 2) 
entry: (objectData at: 3). 

A S e 1 f. 

The first method, the class method, simply calls the second method, 
the instance method, and passes it aStream. Notice in the second method 
that we use the stream upTo: method to pull the object out of the stream 
and reject the objDel character. Next, we call on substrings: to separate 
the data items into separate array entries. Then we use the Appoint¬ 
ment instance method, start:end:entry:, to convert the data and fill in 
the instance variables. 


Booking Appointments 

Having completed the changes to the Appointment class, let’s move on 
to the class which holds appointments, AppointmentBook. 

We want to find a way to store the appointment collection in a way we 
can retrieve it. We can assume that storage of appointments relies on 
the storeTo: method we just developed. What’s left is how to store each 
day’s appointments. To review, the appointments are collected in a Dic¬ 
tionary, the keys of which are dates and the values of which are sorted 
collections of appointments. 
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We can think of the data in the Dictionary as a series of lines, each 
containing a key to its value. Each of these records needs to be stored 
separate from the rest. Should we use the same delimiter as the one 
separating the appointment data? No, this would create a parsing night¬ 
mare. We need another obscure delimiter. How about the character rep¬ 
resented by the integer zero? 

Now that we’ve worked through these issues, we can start on the 
AppointmentBook class storage method. The method loops through the 
Dictionary, building lines of data from the key and value. The value re¬ 
quires us to start an independent loop on this collection, which in turn 
makes each appointment store itself. The storage medium is a stream 
passed as an argument to the method. In order to make the method 
more generic and open up its access, it must be a class method. The 
code for this method is listed below: 

storeAl1AppointmentsOn: aStream 

"save the current set of appointments stored in my class var" 

I del endRec:| 

endRec := Character value: 0. 
del := Character value: 255. 

"Now pass through the dictionary to find keys and values to store" 
Appointments isNil if True: [ A ni V].. 

Appointments associationsDo: [:a | 

aStream nextPutAll: a key printstring; nextPut: del. 
a value do: [:apt | apt storeTo: aStream]. 
aStream nextPut: endRec]. 

"done so answer aStream" 

A aStream 

That’s all there is to storing appointments since the appointment it¬ 
self is doing most of the work. Notice that we added the key to the begin¬ 
ning of the line of data, delimited with the same character used to de¬ 
limit the appointment data. 

Regarding the associationsDo: message, a Dictionary stores each key- 
value pair in a single object instance of the Association class. The mes¬ 
sage allows us to access these objects. So instead of looping on the val¬ 
ues and using them to find the keys, or vice versa, we essentially loop on 
both. We access the key with the key message and the value with the 
value message. Notice the loop through the value’s collection where we 
call the appointment method storeTo:. 
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The stream creation and management has been left to the caller. The 
method stores its data on the provided stream and returns it without 
regard to the stream’s origin or contents. The use of streams often re¬ 
sults in more generic code. We end up with a method that is compact 
and at the point that a good method should be. 


Restoration of Appointments 

Next we develop the restore method. This method parses the data and 
puts it back into the appropriate objects. Much of the labor of this as¬ 
signment can be delegated to existing methods which already create 
and manage the objects we require. 

Lets examine this in more detail, starting with the appointments col¬ 
lection itself. To determine how this collection is created let’s look to the 
initialize method: 

initialize 

"make sure appointment book is pointing 

at stored appointments" 

appointments := self class appointments. 

which points us to the class method appointments: 

appointments 

"Answer Appointments after making sure it is initialized" 
Appointments isNil ifTrue: [ Appointments := Dictionary new]. 
A Appointments 

We can see that to create a new appointments collection we must first 
set the Appointments class variable to nil, then call this method. That’s 
okay for now, but how do we create a new Dictionary entry from the 
string data we have? Since the user enters each of these items as a string, 
we must have a method which takes these strings, creates an appoint¬ 
ment object, and stores it in the appointments Dictionary. Indeed we do. 
The method is called start:end:entry:. Let’s look at its code: 

start: startTime end: endTime entry: aString 

"create a new appt with startTime, endTime and aString 
answer revised collection" 

| appt appts | 

appt := Appointment start: startTime end: endTime entry: aString. 
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appts := seif appointmentsAt: currentDate. 

appts isNil ifTrue: [appts : = appointments at: currentDate put: self 
newSchedule]. 
appts add: appt. 

A self getCurrentDaySchedule 

Analysis shows that the method takes three strings and answers the 
current day’s schedule, which we can safely ignore here. It also seems 
dependent on the instance variable currentDate. This variable is being 
used to retrieve appointments, as well as set them. Therefore, we can 
conclude it assigns the Dictionary key. This is very good, since we need 
to manipulate the Dictionary key to restore appointments. We just need 
to make sure we restore this variable to its original value. The method 
also handles the creation of the schedule Collection for us. Except for 
the first line, the method is exactly what we need. The first line is a 
problem since we already have an appointment and don’t need a new 
one. Perhaps if we split this method into two methods, one which cre¬ 
ates an appointment and one which adds it to the Dictionary, we could 
then call the latter method after having an appointment restore itself. 

This is a perfect example of method refactoring. It is sometimes diffi¬ 
cult to keep methods generic enough. Often, the only time you know how 
much to put into a method is when you’ve created a new method which 
needs only a part of another method’s code. The temptation is to create 
a copy of a method and modify the code as required. However, look at 
the code and see if splitting it into two or more methods would avoid 
copying it. Can you create a new method which can be called by the old 
method and the new method you’re working on? This is similar to the 
issue we discussed in Chapter 13 about whether to override or copy a 
super class’ method. Refactoring is often the foundation of code. Reus¬ 
ing code makes it easier to make changes later on, since you’ll have only 
one method to be concerned with. 

So let’s create a more generic method by breaking the start:end:entry: 
method into two methods. The new method is called addAppointment: 
and is called by the original method. Here is the modified method: 

start: startTime end: endTime entry: aString 

"create a new appt with startTime, endTime and aString 
answer revised collection" 

| appt appts 

appt := Appointment start: startTime end: endTime entry: aString. 
A self addAppointment: appt. 
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And now the new method: 

addAppointment: anAppointment 

"add anAppointment to the currentDate schedule" 

Iappts | 

appts := self appointmentsAt: currentDate. 

appts isNil ifTrue: [appts := appointments at: currentDate put: 

self newSchedule]. 
appts add: anAppointment. 

A self getCurrentDaySchedule 

We can call the new, generic method from our retrieval method and 
thus have two methods calling this method instead of one. 

Since most of the work of retrieval is handled by the Appointment 
methods, we can concentrate on removing the keys from the stream and 
determining when a line of data has been read. The first step is to read 
the key from stream, use it to set the currentDate (using the Date 
fromString: method), then pass the stream to the Appointment restore 
methods. How do we know when a line has completed and we need to 
read another key? We need to be able to determine if the stream con¬ 
tains our special “0 character” before we pass on the stream and, if so, 
start the cycle all over until the end of the stream. 

You’ll recall there is a method called peekFor: which takes a charac¬ 
ter, looks ahead to the next character on the stream, and answers a 
Boolean indicating whether the argument character has been found. The 
advantage of this method is that if the character is found, it is read. If it 
is not found, the stream is left untouched. 

As you may have guessed, we need to use a couple of whileFalse: 
loops to cycle through the stream. The first loop handles the keys, the 
second restores each appointment and adds it to the appointment’s Dic¬ 
tionary. Finally, we set currentDate back to its original value. 

From the description above we can easily create a new instance method 
to restore all appointments from a given stream. The code for the method 
retrieveAUAppointmentsFrom: is as follows: 

retrieveAl1Appointments From: a St ream 

"From a stream create a new Appointments collection" 

| del endRec key appt cDate oldAppointments | 
endRec := Character value: 0. 
del := Character value: 255. 

Appoi ntments := nil. 
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appointments := self class appointments. "To create a new 
appointments collection" 

cDate := currentDate. "So we can restore existing state" 

[aStream at End] 
whileFalse: [ 
key aStream upTo: del. 
currentDate := (Date fromString: (key)). 

[aStream peekFor: end Rec] 
whileFalse: [ 

appt := Appointment restoreFrom: aStream. 
self addAppointment: appt. 

]. 

]. 

currentDate := cDate. 

There shouldn’t be any surprises here. All is as we described. Notice 
how this code and the storage code are completely isolated from the 
internal make-up of an appointment object. Our responsibility here is 
restricted to calling the appropriate methods, and does not include read¬ 
ing or setting instance variables. That is handled for us by the object 
itself. 

To keep things balanced, let’s add an instance version of the 
storeAllAppointmentsOn: method which calls the class version. This ex¬ 
tra method makes access more uniform for operations which are work¬ 
ing with an instance of this class. 

storeAllAppointmentsOn: aStream 

A se1f class storeAllAppointmentsOn: aStream 

This completes the methods for this class. The actual file handling 
methods are added to the AppointmentBookWindow class, thus keep¬ 
ing user I/O in the Window class. 


Working with Fifes 

AppointmentBookWindow is our next focus. This is the class which his¬ 
torically has handled user interaction; therefore it seems the right place 
for file handling as well, especially when you consider that we need to 
get user input to determine the file’s name and location. The major work 
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of storage and retrieval are delegated to other classes. All this class has 
to do is open and close files. 

First, we need to know the name and location of the file. IBM Smalltalk 
provides us access to the host operating system’s standard file dialog, so 
we use this dialog to request this information from our user. The class 
CwFileSelectionPrompter manages this dialog. Let’s set a window prompt 
or title, a search mask to determine which files to display, and a default 
filename. The dialog answers nil if the user cancels, or a file path string 
which can then be used to open the file. You can test this dialog by se¬ 
lecting and displaying the following code segment: 

CwFileSelectionPrompter new 

title: 'Save All Appointments'; 
searchMask: ' *.apt'; 
fileName: 'all.apt'; 
prompt. 

We can take the path string provided by the dialog and use it to open 
a file using the CfsWriteFileStream instance method openEmpty: for stor¬ 
age and, for retrieval, the CfsReadFileStream instance method open. 
Once we have an open file, we need only call the AppointmentBook 
method from those we just wrote and close the file. We can handle both 
storage and retrieval with the same method by taking advantage of the 
callback format and using the clientData argument to indicate which 
operation to perform. With this argument, we can determine how to 
deal with differences in saving and restoring the appointment’s data. We 
present you with the new method: 

accessAppointmentsFi1e: widget clientData: type cal 1 Data : ignore 
"Access an Appointment File, then call appropiate 
apptBook method based on clientData" 

| title file | 

type = #save 

ifTrue: [ title := 'Save All Appointments'] 
ifFalse: [title : = 'Restore All Appointments']. 

file := CwFi1eSelectionPrompter new 
title: title; 
searchMask: '*.a p t'; 
fileName: 'all.apt'; 
prompt. 
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file is Nil ifTrue: [ A self]. 

"Open the file " 
type = #save 

ifTrue: [ (file := CfsWriteFi1eStream openEmpty: file) 
isCfsError 

ifTrue: [ A self error: file message]. 
apptBook storeAl1AppointmentsOn : file] 

ifFalse: [ (file := CfsReadFi1eStream open: file) isCfsError 
ifTrue: [ A self error: file message]. 

apptBook retrieveAl1AppointmentsFrom: file, 
self broadcast: #newAppointment]. 

"done so close file" 
file close. 

This method has it all: use of the File prompter, opening of the file, a 
call to the AppointmentBook methods, and the closing of the file. Best of 
all, it can distinguish between two operations. What more could you ask 
for in a method this size? How about a broadcast of a new appointment? 
Notice that’s exactly what we do when we are done restoring the data. 
Our next and final step is to give the user access to this method. 

Tiie Final Step 

We’ve finished developing all the code to perform storage and restora¬ 
tion of appointments. What’s left is to provide a way for the user to ini¬ 
tiate the processes. We first link the above method to the existing menu 
structure. This gives us two menu items, one each for saving and re¬ 
trieving all appointments. Let’s add these items and a separator before 
the “Display Appointment Chart” item. We present only a portion of the 
code, to help you locate the correct position of these new items. The 
added code is in bold: 

addMenuBar: a MainWindow 

"Add the 5 menu buttons to the window" 

| item menuBar form subMenu subMenu2 form2 | 

menuBar:=aMainWindow createMenuBar: 'menu' 
argBlock: nil. 
menuBar manageChi1d. 



IBM SMALLTALK 


item := form2 

createPushButton: 'Today' 
argB1ock: nil. 

item addCa11 back: XmNactivateCal1 back 
receiver: self 

selector: //today: cl i ent Data : call Data : 
clientData: nil. 
itern manageChi1d. 

item := form2 

createSeparator: 's ep' 
argB1ock: nil. 
item manageChild. 

item := form2 

createPushButton: 'Save All Appointments' 
argBlock: ni 1 . 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: //access Appoi ntments Fi le:clientData:callData: 
cl i entData: //save, 
itern manageChi1d. 

item := form2 

createPushButton: 'Retrieve All Appointments' 
argBlock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

sel ector -.//accessAppoi ntments Fi le:clientData:callData: 
clientData: //retrieve.- 
i tern manageChi1d. 

item := form2 

createSeparator: 'sep' 
argBlock: nil. 
item manageChild. 
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item := form2 

createPushButton: 'Display Appointment Chart' 
a r g B1o c k: nil. 

item addCa11 back: XmNactivateCal 1 back 
receiver: self 

selector: #displayPlot:clientData:cal 1 Data: 
c1ie n t D a t a: nil. 
itern manageChi 1 d . 


The Road Tost 

Having completed all the code, we are ready for another smoke test. We 
will stand by while you kick the tires and go for a test drive. While on 
your journey you may find it fun to see how the application handles 
single as well as multiple daily appointments. You may also want to add 
appointments after saving and seeing whether these appointments are 
there after you restore. Now is also the time to play with the test files 
(*.apt) in the chapter’s directory. 

In the next few chapters, we will deal with multiprocessing and tackle 
one last project to complete our application. In the meantime, take the 
SimplePIM application for a spin. 




CHAPTER 



From its beginning, Smalltalk has supported multiprocessing (the simul¬ 
taneous execution of two or more separate tasks). IBM Smalltalk pro¬ 
vides five classes that support multiprocessing. In this chapter, we’ll look 
at each of these classes and its capabilities. 

It may seem at the outset that this discussion is an interesting aca¬ 
demic exercise that teaches some intriguing concepts. But, as you’ll see 
in Chapter 17, the ability to handle multiple processes concurrently fa¬ 
cilitates the development of some kinds of applications. In addition, 
multiprocessing makes it possible for the Debugger windows to operate. 
If you’re curious about this subject, take a look at those windows and 
their methods. 

We begin to explore multiprocessing by discussing the process by which 
IBM Smalltalk normally processes events and 

There are a significant number of examples in this chapter. If you 
prefer not to type them in, you can find them on the disk under the 
chaplb folder or directory in the file chapl6.wsp on the disk accompa¬ 
nying this book. Open a workspace on this file and follow along. 

How Messages anil Statements Execute 

In the usual case, IBM Smalltalk handles messages synchronously, as 
shown in Figure 16-1. This drawing shows Object A as the sender object 
and Object B as the receiver object. Object A has two messages to send 
to Object B (in a cascaded series, for example). It sends messagel and 
then waits for Object B to return a value to it before sending message2. 
This returned value is the new object to which the second message will 
be sent. In the drawing, we’ve assumed Object B is returned, but that is 
not necessarily the case, as we’ll see shortly. 





The synchronous method of dealing with messages means that there is 
generally a list of pending messages waiting for the completion of previ¬ 
ous messages before it can be sent. This is what we normally want; the 
result returned by Object B in response to messagel may be necessary 
to carry out processing defined by the method in Object B that responds 
to message2. This approach becomes a bottleneck if the action taken by 
Object B in response to messagel requires Object B to send a message to 
another object (see Figure 16-2). 
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Assume that Object A defines a method that contains a statement with 
three parts. The first part generates messagel. Figure 16-2 depicts five 
steps between the sending of messagel by Object A and its ability to 
send message2 to another object, whose identity it doesn’t know until it 
receives the result of the messagel processing. At each stage of this 
processing, there is only one active message. When Step 2 in Figure 16-2 
has executed, for example, messagel 1 is the active message, while mes¬ 
sagel awaits the ability to resume operation. 

In fact, part of the problem in trying to sort out this usual state of 
affairs involves some overloaded and loose terminology that has grown 
up around Smalltalk and OOP. We talk routinely about “objects sending 
messages.” In fact, the normal message send is handled by a Smalltalk 
statement that is, in turn, part of a method that is identified with an 
object. So the connection between the object and the message-send is 
far less direct than it might seem. A statement, as we know, is a series of 
messages terminated by a period, such as: 

Q1 := 'Hel1ospaceoutspacethere'. 

The first message receiver is explicitly named at the beginning of the 
statement. Each successive message receiver is determined by the results 
of each message in the statement. In the example above, then, the first 
message receiver is the string “Hello,” which is explicitly stated. It receives 
the message [comma, which, of course, means to concatenate) and a 
single argument, the keyword “space.” The resulting object is the word 
Hello followed by a space. That object, in turn, is sent the comma mes¬ 
sage and the string argument “Out,” creating the object “Hello Out.” 
When Smalltalk reaches the period at the end of the statement, it looks 
for a new object with which to start another round of message-sending. 

So, you can think of a Smalltalk statement as a serial stream of mes¬ 
sages, each dependent on the result of the previous one. This means 
that messages are handled in a synchronous fashion; each message is 
held until the answer of the previous message is sent, evaluated, and 
answered. However, a group of two or more statements can be handled 
asynchronously, since the individual statements are not dependent on 
each other. 

Each message represents a method, each with its own set of state¬ 
ments. We usually think of each method as a single element of execut¬ 
able code, but in reality it is actually a series of statements, made of a 
series of messages. Thus the tree can become quite complex, with many 
branches waiting to be completed—enough to make your head hurt. As 
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you can see, the virtual machine, or VM (the Smalltalk engine respon¬ 
sible for interpreting and executing your code), has quite a bit to handle 
with just one executing method. 

Let’s look at some examples. Consider two messages, one intended to 
display a message in the Transcript window and the other to cause the 
speakers to beep. The way we would normally expect to write such state¬ 
ments is: 

Transcript cr; show: 'Hello World'. 

CgDisplay default bell: 100. 

In this case, the two messages are posted simultaneously. The VM can 
execute both statements at its leisure; there are no expectations placed 
into the code, since the two statements are completely independent of 
one another’s results. This approach to method execution is sometimes 
referred to as post-and-deferred. 

Now let’s see how those same messages can be turned into thread- 
related statements: 

[Transcript cr; show: 'Hello World'] fork. 

[CgDisplay default bell: 100] fork. 

In this case, each message is evaluated completely before being posted. 
They are posted in the order of their completion. The VM executes each 
message in its own process, and the two processes are executed as soon 
as they are posted to the VM. 


Process States 

Once started, a process can be in one of three states until it is destroyed: 


■ ready , meaning it can be executed 

a blocked , meaning it is waiting for a semaphore to receive a signal to 
balance a previously issued wait signal before it can continue 
m active , meaning it is now executing 

Processes typically move back and forth between ready and active 
during their lives as IBM Smalltalk messengers. You can directly control 
the state of a thread by using its associated Semaphore object, or by send¬ 
ing it an interrupt. Both approaches will be described later in the chapter. 
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Process Priorities 

An instance of the class Process can be assigned a priority ranging from 
1 (the lowest) to 7 (the highest). In IBM Smalltalk, process priorities 
should not be assigned directly but instead should be assigned using the 
ProcessScheduler methods in Table 16-1. For example, to fork a pro¬ 
cess at system background priority, use 

[Transcript or; show: 'Hello world'.] forkAt: (Processor system back¬ 
ground priority) . 

Processes are assigned a priority when they are created, which stays 
with them throughout their processing, unless explicitly changed. Fork¬ 
ing a process without specifying a priority gives it the same priority as 
the process which forked it. 

Table 16-1. Processor Access Methods for Setting Process Priorities 


ACCESS METHOD NAME DESCRIPTION 


systemBackyroundPriority The priority of a system background process; this 

is the lowest priority 

userBackgroondPriority The priority of a user background process, which 

refers to a UlProcess, not the end-user. 

aserScheduiingPiiority The priority of a user interface process, the default 

priority of any UlProcess forked by the user inter¬ 
face 

userlnterruptPriority The priority of any UlProcess forked by the user 

interface that should be executed immediately 
lowIOPriority The usual priority of input/output processes 

highlOPriority The priority of the process monitoring the local net¬ 

work devices 

timingPrlority The priority of the process monitoring the real-time 

clock; the highest priority 

Waiting Time 

Each time IBM Smalltalk is ready to handle another message in the stacks, 
it looks first at its priorities. In the event of a tie, it looks at the length of 
time each process has been awaiting processing. The one that has been 
waiting the longest is processed next. Of course, in practice, it is nearly 
impossible to predit which of two waiting processes of the same priority- 
will be handled next. 
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Multiprocessing Approaches 

There are two basic types of multiprocessing: preemptive and non-pre- 
emptive. 

In preemptive multiprocessing designs, each process is allocated a 
predefined amount of processor time in which to execute. At the end of 
that time, if not complete, its processing is suspended and the next mes¬ 
sage or process awaiting execution gets its share of the time. This ap¬ 
proach is sometimes called time-slicing. 

Non-preemptive multiprocessing uses a technique other than a pre¬ 
defined amount of time to determine when to switch processes. There 
are many approaches to this. IBM Smalltalk’s approach combines prior¬ 
ity and waiting time of pending processes with the state of the active 
process. In any non-preemptive multiprocessing design, the designer must 
come up with a well-defined protocol for determining when to switch 
processes. A real-life example should clarify the distinction between these 
two approaches. 

Imagine that you are a busy person who gets a lot of telephone calls. 
You are engaged in a telephone conversation with your biggest customer 
when your stockbroker calls with a hot tip. You have to decide whether 
to put the customer on hold (or terminate the conversation) and take 
your broker’s call, or whether to keep talking to your customer and de¬ 
lay the conversation with your broker. You are using priority-based de¬ 
cision making to decide when to respond to the next message. If the next 
call is from your spouse, that may alter your priorities yet again. In this 
example, you are operating in a non-preemptive multiprocessing mode. 

On the other hand, imagine working in a situation where your com¬ 
pany had decided that three minutes is enough time for any call. Imag¬ 
ine that your company installed equipment that kept track of how long 
you were on a call, terminated any unfinished call after three minutes, 
and brought the next call waiting in the queue to your line. In this ex¬ 
ample, you’d have a preemptive multiprocessing system. 



Even though they use similar terminology, you should know that there are significant 
differences between Windows or OS/2 tasks and IBM Smalltalk processes. It is easy 
to get them confused. Although Smalltalk code can execute in different Smalltalk 
processes, the Smalltalk environment operates in its own OS/2 or Windows process. 
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The Common Process Model 

Multiprocessing is managed by the classes in the IBM Smalltalk 
subapplication CPM, which stands for Common Process Model. CPM is a 
subapplication of Kernel, so it is available to any application with Kernel 
as a prerequisite. 

IBM Smalltalk’s approach to non-preemptive multiprocessing involves 
five classes, as we indicated at the beginning of the chapter. Let’s take a 
look at each of these classes. 


Process 

The class Process is an Object subclass whose instances represent a 
sequence of message sends that are executed independently. Processes 
are usually created as a result of forking a block, just as we did above. 
Each process has priorities which determine how quickly and how often 
it is processed. 

Among the instance methods of class Process, the most important are: 

m resume, which resumes a process and makes it ready 

■ suspend , which puts the process in a suspended state 

m terminate, which ends the processing life of a process and prepares 
it for garbage collection 

m priority: and priority, which set and get a process’ priority 

■ printOn:, which displays the process as “ClassName:Name{state,- 
priority}” 

m yield:, which allows other processes to work 


Unlike most objects, processes are not created with the new message. 
Rather, you fork a process by sending a message to a block. 

In the example above we used the fork method which creates a new 
process for the receiver block at the current active priority. The forkAt: 
method takes an argument of the priority (remember to use Process- 
Scheduler methods for this) and creates a process with the given priority. 

Both of these methods create ready processes. To create a suspended 
process, use the newProcess method. You can pass an argument while 
creating a suspended process by including it with the message 
n e w Process Wi th :. 



UfProcess 


The class UlProcess is a subclass of Process. It is a process specialized 
for handling user interface processing. There should be only one in¬ 
stance of this process running at any time. The methods resume and 
terminate have been modified to ensure this is the case. The current UI 
process can be accessed by sending the message currentUI to the class. 


ProcessScheduEer 

The class ProcessScheduler is one of the few IBM Smalltalk classes de¬ 
signed to have only one instance. The single instance of this class can be 
retrieved via the global variable Processor. 

ProcessScheduler is a subclass of Object. Instances of the 
ProcessScheduler class handle all the scheduling and processing of syn¬ 
chronous user interface events, process scheduling, and VM (interrupt) 
signal handling. 

The Processor has only one “real/active” instance at any given time. If 
the Processor encounters a fatal exception, the VM creates a new Pro¬ 
cessor and gives it all the attributes of the previous (halted) Processor. 

As its name implies, the Processor schedules message handling and 
processing. It does this primarily by manipulating an instance variable 
called ready. This variable is an array of EsQueue, a linked-list queue. 
There is a one-for-one correlation between a particular queue’s index, 
its location in the array ready , and its priority. A process with a priority 
of 1 accesses the method systemBackgroundPriority and is in the first 
position of the array. Processes with a priority of 4 access the method 
userlnterruptPriority and share the fourth position in the array. Each 
array index, then, corresponds to a priority rating. If multiple processes 
share the same priority, are at the same index location, then their posi¬ 
tions in the queue become relevant. Since processes are added to the 
end of the queue, the first process has been waiting the longest. 

The debugging of processes is also handled by this class. Several pri¬ 
vate methods aid the Debugger in processing debugged processes. 

The Processor is also responsible for scheduling all the processes in 
the environment, including itself. It schedules processes via a priori¬ 
tized, round-robin scheme. It gives special preference to itself to ensure 
rapid user interface response time. 

In addition to the ones covered in Table 16-1, the key methods of this 
class are the following: 
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m activeProcess calls a primitive which answers the currently ex¬ 
ecuting process 

m activePriority&nswers the priority that the scheduler is working 
on now 

m signal:atTime: takes a semaphore and millisecond time value and 
creates a block which delays until the given number of millisec¬ 
onds, then signals the given semaphore; it runs only one time 


Semaphore 

Semaphore is an Object subclass that supports IBM Smalltalk’s sema¬ 
phore framework. Instances of the class Semaphore are used as flags to 
control the state of an individual Process. When you create a new pro¬ 
cess, you will also generally create a new instance of the class Sema¬ 
phore. (As we will see later in the chapter, you sometimes create two or 
more processes that share a semaphore.) Figure 16-3 shows the interre¬ 
lationship of these two objects. 


Process Semaphore 


Awaiting 

Wait 

© 

Decrement 

SignalCount 

an event 

Message 
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Figure 16-3. 


Interaction between a process and semaphore 
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The wait and signal methods are the only ones of interest in Sema¬ 
phore. The two instance variables shown in Figure 16-3 ( count and 
waitingProcessess ) are the important parts of this class. The former stores 
the number of signal messages minus the number of wait messages sent 
to the Semaphore object during its lifetime. The latter is an 
OrderedCollection of processes that have been sent a wait message with¬ 
out sending a corresponding signal message. 

Two more methods, forMutalExclusion and critical:, are involved in a 
process known as mutual exclusion (“mutex” for short). Mutex sema¬ 
phores are involved in managing a shared resource, such as a printer, 
file, or shared variable. 

Mutex gives a process exclusive access to the resource, and all others 
must wait until that process is finished with the resource. This differs 
from the normal way processes work because the process completes its 
work before the next process begins. This is called “run to completion” 
and is the opposite of preemptive. 

If you think about a printer receiving text from two processes, you 
will understand why mutex is important. Under normal processing, a 
word or two, depending on the time slice, would be printed from each 
process each time it was scheduled, making the printout interesting but 
not very readable. Instead, if each process in turn printed its text in full, 
then the printout would certainly be readable (assuming the text was 
readable to begin with). Giving each process exclusive access to the 
printer allows them to share the printer without corrupting the printout. 

Some Examples of Multiprocessing 

Even though Chapter 17 contains a sample application that implements 
multiprocessing, there are so many ways of approaching the design is¬ 
sue that we will deviate from our usual practice of confining these theory- 
discussion chapters to the classes and methods. Let’s take a quick look 
at a few playful examples of multiprocessing implementations. 

In a Workspace, type and execute the following lines: 

[Transcript show: ' Smalltalk ' ] fork. 

Transcript show: 'Programming'; cr. 

We expect the Transcript to display as a result the words “Smalltalk 
Programming.” However, we got: 
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Programming 
Smal1talk 

What gives? Shouldn’t the forked process run first? Well yes, except 
this is an example of mutex. The Transcript (and Workspace) is treated 
by IBM Smalltalk as a mutually exclusive resource and the UlProcess 
gets first crack at this resource. The forked process has to wait until the 
UlProcess completes. 

A better example of this is: 

[Transcript show: ' Smalltalk ' ] forkAt: Processor 
userSchedulingPriority. 

[Transcript show: 'Programming'; cr] forkAt: Processor 
1owIOPriority. 

Although the second process has a higher priority, the first prints. 
Again we see an example of mutex: the first process is started and grabs 
the Transcript, forcing the second, higher priority process to wait. 

The interactions of processes are more interesting if the blocks of 
code being executed do something more exciting than display words. 
Let’s look at an example using counting processes. We’ll first show the 
normal way that IBM Smalltalk handles such tasks. Type and execute 
the following lines: 

Transcript cr. 

[1 to: 10 by: 2 do: [ :i | Transcript show: i printstring ]] forkAt: 
Processor userSchedulingPriority. 

[0 to: 10 by: 2 do: [ :i | Transcript show: i printString]] forkAt: 
Processor userSchedulingPriority 

The Transcript should show the numbers (the actual order depends 
on your system): 

102354796810 

By changing the order of the processes we can use mutex to display 
the correct sequence like this (enter the text and execute it): 
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Transcript cr. 

[0 to: 10 by: 2 do: [ :i | Transcript show: i printstring ]] 
forkAt: Processor userSchedulingPriority. 

[1 to: 10 by: 2 do: [ fpj | Transcript show: i pri ntSt ri ng] ] forkAt: 
Processor userSchedulingPriority 

How about that, the correct order! Remember, mutex is a semaphore, 
so although we have never actually created a semaphore, the Transcript 
runs off of one. In the next set of examples we will work with sema¬ 
phores of our own creation. 

Semaphores 

Without mutex, it is actually impossible to predict the order in which the 
values will appear. As you can see, the processes are executing one after 
another, intermingling the numeric outputs as they do so. We are at the 
mercy of the Processor as to how often and how long each process is 
run. We need a traffic signal to control the processes and manage their 
execution. Semaphore is just such a traffic signal. Try the following code: 

| sem semi | 

sem := Semaphore new. 
semi := Semaphore new. 

Transcript cr. 

( [sem wait. 1 to: 10 by: 2 do: [ :i | Transcript show: 
printstring, semi signal, sem wait ]] 
forkAt: Processor userSchedulingPriority) name: 'Process A'. 

( [ 0 to: 10 by: 2 do: [ :i | Transcript show: i printstring, sem 
signal . semi wait]] 

forkAt: Processor userSchedulingPriority) name: 'Process B'. 

By using semaphores, we have created a parallel counting machine 
that turns out the numbers in their correct order. 

The sem wait message before the counting loop in Process A ensures 
that Process B begins the counting. This suspends Process A. Process B 
starts, displays its first number, and then uses sem signal to notify Pro¬ 
cessor A’s semaphore that it can proceed. It is important to note, how¬ 
ever, that this alone does not start Process A; it simply makes that pro- 
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cess ready. In this case, the two states are hard to distinguish, but imagine 
if we had 3, 10, or 150 processes at work. Here, the next process in the 
queue is Proc ess A, so it prints its first number, then sends a signal message 
to semi, alerting Process B that it can now move to ready status. It also 
sends a wait message to the semaphore with which it is associated. 

Another important point is that the wait message only affects the process 
from which it is sent. A signal message, on the other hand, affects all sus¬ 
pended processes by enabling them to consider changing their status. 

We should point out two things about this code. First, name: is a pri¬ 
vate Process instance method which assigns the process a name. Pro¬ 
cesses are normally named when created. We are overriding the default 
to make the process easier to see in Processor inspector. Second, we 
added one iteration to Process A’s loop so that a final signal would com¬ 
plete Process B. 

Using a Single Semaphore 

We can create the same result by using a single semaphore combined 
with diff erent process priorities. Here is an example for you to execute: 

| sem | 

sem := Semaphore new. 

Transcript cr. 

( [ 1 to: 11 by: 2 do: [ :i | Transcript show: i printstring, sem 
signal ]] 

forkAt: Processor userBackgroundPriority) name: 'Process A’. 

( [ 0 to: 10 by: 2 do: [ :i | Transcript show: i printstring, sem 
wait]] 

forkAt: Processor userSchedulingPriority) name: ’Process B’. 

Actually we only need the priority difference for the first execution of 
each block. The reason is that if they were the same priority, the Process 
A signal would occur before Process B waited, resulting in Process B 
never waiting. .After the first block iteration, the semaphore takes over 
so the priorities are irrelevant. 
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Inspecting Processor 

Inspect the Processor by selecting the word in the code above and select¬ 
ing Inspect from the popup menu. You can now look at the variable ready 
and see its array. Inspecting this array lets you view each priority queue. 

The queuelnterrupt: Method Exposed 

In this section we take a detailed look at the Process instance method 
queuelnterrupt:. As we discussed earlier, this method interrupts the re¬ 
ceiver process and forces the given block to be executed. Here is an 
example of the method’s use: 

H |st p | st := Time now. [ (Time now subtractTime: st ) 
seconds >5 ] 

whileFalse: [ 
p := UlProcess currentUI. 

Transcript show: Processor activeProcess printstring, 
p queuelnterrupt: [ Transcript cr; show: 'Interrupt: \p 
printString]. 

]. 

] forkAt: Processor 1owIOPriority) name: 'QI Example’. 

Execute this code and watch the Transcript. After five seconds the 
text stops. Notice how the process is interrupted and the block given to 
the queuelnterupt: method is executed instead. 

There are a couple of points of interest about this code. Note how we 
create temporary block variables. They use the same format as method 
temporary variables. They can even be added after block arguments. 
Not all implementations of IBM Smalltalk allow blocks to have tempo¬ 
rary variables. 

The timing is determined by comparing the current time to the time 
stored in the variable. The active process when the block executes is 
always ourselves; how else could this code be executing? 
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Process Watcher 

The previous example was an interesting example of the queuelnterrupt: 
method, but not of processes in general. Wouldn’t it be nice if we could 
track the state of our processes without interactively testing their ex¬ 
ecution state! Well, we can do so quite easily by creating yet another 
process block. Here is the code: 

([ | st p ps I st := Time now. [ (Time now subt ractTI me: st ) seconds 
>30 ] 

while False: [ 

p := UlProcess currentUI. 
ps ^Processor al1 Processes. 

Transcript cr; show: ' 

l to: ps size do: [:1 | Transcript cr; show: (ps at: 1) printstring], 
p queuelnterrupt: [ Transcript cr; show: 'Interrupt: \p 

printstring]. 

(Delay forSeconds: 3) wait]. 

] forkAt: Processor 1owIOPriority) name: 'Process Watcher'. 

We extended the previous block example to gather all processes, on 
each execution, and display them in the Transcript. To make it easier to 
read the results we added a delay using the Delay class. We call the 
process “Process Watcher.” Enter the above code and execute it. Figure 
16-4 shows the results after running the Process Watcher code. 
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System Transcript 


File Edit Smalltalk tools 


Process: Process Watcher{runniing,5} 
Process:CwAsyncIGProcess{suspended,4} 
Process:UI Idle Process 6:26:07 PM{ready,l} 
UIProcess:3794{ready,3} 

Interrupt: UIPmcess:3794{mnmng,3} 


Process:Process Watcher{runniing,5} 
Process:CwAsyncIQProcess{siJspended,4} 
Process:UI Idle Process 6:26:07 PM {ready,!} 
UlProcess:3794{ready,3} 

Interrupt: UIProcess:3794{running,3} 


Process:Process Watcher{runnlng,5} 
Process:CwAsyncIOProcess{suspended,4} 
Process:UI Idle Process 6:26:07 PM {ready,!} 



Figure 16-4. 


The results of the Process Watcher code 


Enhanced Process Watcher 

Try running more than one Process Watcher at a time. The result is 
somewhat confused, as each process outputs a portion of its information 
at the same time. If we put the text in its own window then perhaps we 
could view several watchers at the same time. Here is the modified Pro¬ 
cess Watcher code: 

"Process Watcher window demo" 

I ws | 

ws := EtWorkspace new open. 

([ | st p ps | st := Time now. [ (Time now subt ractTi me: st ) minutes 
>1 ] 

whileFalse: [ 

p := UlProcess currentUI. 
ps :=Processor al1 Processes . 
ws textWidget setstring: '- 
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1 to: ps size do: [:| | ws cr; show: (ps at: i) printstring], 
p queuelnterrupt: [ ws cr; show: ’Interrupt: ',p printstring]. 
(Delay forSeconds: 3) wait]. 

ws close] forkAt: Processor 1owIOPriority) name: 'Process Watcher’. 

Once again we enlist the aid of the Workspace to display our text. The 
window is closed just before the block terminates. We increased the time 
to a minute so we could see the effect of launching multiple Process 
Watchers. Figure 16-5 displays this new window in action. 

Run multiple Process Watchers and see each new process be added to 
the list; and as they time out, watch them disappear from the list. 


A Time-Based Semaphore 

In our discussion of the ProcessScheduler class we introduced the in¬ 
stance method signal:atTime: which takes a given semaphore and a mil¬ 
lisecond clock value. The semaphore is signaled when the clock value is 
reached. This method combines a Delay (created with the class method 
forMilliseconds:) with a Semaphore. The significance of this method may 
not be apparent at first. What it allows is to delay a semaphore signal for 
a given time period, creating a time-based semaphore. 


IB Workspace 


3 

File Edit 

Process:Process Watch e ^running, 5} 
Pmcess:CwAsyncl0Process{suspended,4} 

Process:UI Idle Process 6:26:07 PMfready,!} 
UlProcess^O^fready^} 

Interrupt: UIProcess:3794{running,3} 

♦j 

2 - 

l±l r J . -.-! 




A Process Watcher window in action 


Figure 16-5. 
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We said the second parameter is a millisecond clock value. What ex¬ 
actly is this? It is the number of milliseconds since midnight. The Time 
class method millisecondClockValue , appropriately named, answers this 
value as an integer. To set a millisecond clock value one second in the 
future we add 1,000 to the Time method’s result (1,000 milliseconds in a 
second). 

Think about the structure of the Process Watcher. It uses a Delay to 
wait for a period of time between displays. Using a time-based sema¬ 
phore we could instead create a Watcher engine that would drive other 
processes to be displayed in its window. The engine would be a shared 
resource for all processes to use. 

We will need four global variables and a semaphore to track the win¬ 
dow. To make the example more interesting we will give each process a 
unique name and display the total number of Watcher processes run¬ 
ning. We need two more globals because we need to share these vari¬ 
ables among blocks, and a global variable is the easiest way to do this. 
To create these globals, enter and execute the code below: 

Smalltalk at:#Tigger put: 0. 

Smalltalk at:#Nancy put: 0. 

Smalltalk at: #Scott put: 0. 

Smalltalk at: #Molly put: 0. 

A New Process Watcher 

First, we create a Watcher process taken from Process Watcher code 
above. The Watcher still has a termination time, but its delay is replaced 
by a semaphore wait message. We then have the process display the 
total number of Watchers and their termination times, in addition to the 
processes list. The process terminates when either it times out or the 
engine window is closed. For this reason we use a flag to test the loop, 
instead of a time. Here is the code: 

Scott := Scott + 1. 

Molly := Molly + 1. 

([ | st p ps flag t | st := Time f romSeconds: Time now asSeconds + 120. 
flag :=true. 

[flag] whileTrue: [ 

p := UlProcess currentUI. 
ps :=Processor al1 Processes. 
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Tigger shell isDestroyed 
i f F a 1 s e : [ 

Tigger textWidget setstring: Molly printstring, ' Watchers 
Terminates at: st printstring. 

1 so: ps size do: [:i | Tigger cr; show: (ps at: i) 
printString]. 

] 

ifTrue : [flag := fa 1se]. 
t := Time now . 
st < t 

ifFalse: [ Nancy wait] 
ifTrue: [f1ag := false]. 

]. 

Molly := Molly - 1 ] forkAt: Processor 1owIOPriority) name: 'Process 
Watcher ' .Scott printstring. 

We start by incrementing our ID and counter by 1. The ID is concat¬ 
enated to the name to provide a unique name for each process. The 
counter is decremented when the block exits. The rest of the code dis¬ 
plays a header and process list, testing first to make sure a window 
exists for the display. 


The Process Watcher Engine 

Next, we create an engine from the Process Watcher code above. The 
engine does not display process data, it just drives process watchers to 
do so. The engine remains running as long as the window is open. Here 
is the engine code: 

Tigger := EtWorkspace new open. 

Nancy := Semaphore new. 

Scott := 0. 

Mol 1y := 0. 

([ I t | 

t := 0. 

[Tigger shell isDestroyed] whileFalse: [ 
t > Scott ifTrue: [ t :=0]. 
t : = t + 1 . 

Molly > 0 

ifTrue: [Processor signal: Nancy atTime: Time mi 11 i secondClockValue 
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+ (1000*(t+l)). 

] 

ifFalse: [Tigger textWidget setString: '- Empty']. 

(Delay forSeconds: Molly + 3 ) wait. 

] 

] forkAt: Processor 1owIOPriority) name: 'Process Watcher Engine'. 

Although it appears complicated, the code simply loops around, sig¬ 
naling a semaphore after first delaying for a period of time (equal to the 
number of Watcher processes plus an offset). The delay time for the 
semaphore is staggered using the processes number plus 1, in order to 
keep processes from hitting at the same time. The loop is dependent on 
the existence of the window. 

We also test to see whether any Watchers are running, and we display 
text but do not signal the semaphore. Signaling the semaphore without 
any Watchers would cause the signals to collect, so that when a process 
started it would not actually wait until all the signals had been used. 

Watching the Watcher 

Start the engine, then start several Watchers. You will be able to see not 
only the Watchers but also the delay process. As each process times out, 
you will see the count decrement, the process change to the dead state, 
and finally drop off the list. See Figure 16-6. 

Driving the Watchers gives the engine control over when things hap¬ 
pen. Our engine is a mini-scheduler, coordinating display updates. You 
may find the engine to be useful when debugging your own multipro¬ 
cessing code, since you will be able to track the state of your processes. 
To debug multiple processes, open the Debugger (select Open Debugger 
from Smalltalk Tools). From the Debugger, select Process and Debug 
Other and you will be presented with a list of processes to debug. 

In the next chapter we will use what we have learned here to build a 
multiprocessing application. 
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Workspace 


■ Terminates at: 2:24:53 AM 


File Edit 

3 Watchers 
Process:Process Watcher 1 Jfrunning.B} 
Process:Process Watcher 16{suspended,5} 
Process:Process Watcher 15{suspended,5} 
Process:Process Watcher Engine{suspended,5} 
Process:5271 {suspended^} 
Process:5270{suspended,4} 
Process:52£i9{dead J 4} 

Process:Process Watcher 3{suspended,5} 
UlProcess:3806{suspended,3} 
Process:CwAsynclOProcess{suspended,4} 
Process:Ul Idle Process 6:26:07 PM{readyJ} 
UIPmcess:5139{ready,3} 



Figure 16-6. 


A Process Watcher engine window dispatching three Process Watchers 


W 





CHAPTER 


The Final Project: 

A Mimrnrn Clock 


In this chapter, we’ll make our final addition to our SimplePIM applica¬ 
tion by adding a clock. Using the multiprocessing capabilities discussed 
in Chapter 16, we ll describe how to build a clock that can run while 
other IBM Smalltalk application processes are underway. 

The Chapter Files 

This chapter supports the Jilemein.st file introduced in the last two project 
chapters. This file loads all the files required for this chapter. If you 
prefer, load the files as we need them. The names of the files are clock, st, 
clckwndw.st, appctrlr.st, appntmnt.st, apptbook.st, apptbkwn.st, 
caldrwn.st, clock2.st, and setup.st. They reference the Clock, Clock- 
Window, ApplicationController, Appointment, AppointmentBook, 
AppointmentBookWindow, CalendarWindow, and Clock2 classes, as well 
as a modified setUp method for the new clock. 

Designing the Application 

We want the clock portion of our application to support at least two func¬ 
tions. First, it should enable the user to set an alarm on an appointment for 
a given date. Second, it should sound an alarm when it’s appropriate. 

Since we want the clock to work with the SimplePIM application we’ve 
been building in earlier chapters, we need to add a ClockWindow class 
as a new application and as owner of the Clock object. This allows us to 
take a different approach to the use of events in this module. We’re go¬ 
ing to create the Clock class as a subclass of Object and make it a win- 
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dowless object. We aren’t asking the Clock object to display the time, 
just to keep track of it and remind us of appointments. The Clock object, 
then, sends events to its owner as broadcast messages, just like our wid¬ 
get-based Window classes would. However, the Clock object does not 
participate as an ApplicationController object. We leave that responsi¬ 
bility to the ClockWindow class object. The ClockWindow serves as a 
switchboard for the Clock instance and forwards the appropriate events 
to other windows. It will also dispatch to the Clock object queries from 
other windows and itself. 

To keep the clock up to date, we need to handle two situations. The 
first occurs every second, when the time changes and the Clock object 
needs to notify its owner (an instance of ClockWindow) of the new time. 
The second event occurs every night at midnight when the clock must 
reset itself and change the day. 



Of course, the clock also has to keep track of minutes, hours, and days, and notify 
ClockWindow objects of their passage. But since these activities involve larger 
time segments than a second, we can use seconds as the driving force behind event 
notification. As you'll see, this turns out to be a good choice. 


In modeling a real-world clock, we concentrate on the mechanism 
used to track changes in seconds, minutes, and hours. At the heart of 
the Clock object are a series of nested conditional loops. The first of 
these loops is a multiprocessing block that sets up the multiprocessing 
situation. Each loop is designed to call the next higher time increment 
only when its conditions indicate that it should do so. This approach 
resembles the operation of a real clock, where a gear that tracks sec¬ 
onds rotates in such a way that it only advances the minute gear when 
60 seconds have passed. For this design, we need to define four events: 

n # second 
m ttminute 
m #hour 
m #day 
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In addition to creating the Clock class and the ClockWindow class, we 
need to explore how IBM Smalltalk stores and manipulates time. Finally, 
we will create an improved version of the clock, which uses multiple 
semaphores to run separate processes for each gear by subclassing the 
Clock class. 

Working with Tiie 

Since time is clearly at the heart of the matter in this final project, let’s 
first explore the class Time a little. (Actually, Time is a subclass of Mag¬ 
nitude.) Our most important concern is how a time value is stored so 
that our application can make use of it. A little exploration reveals sev¬ 
eral ways we can ask IBM Smalltalk to give us the time: 

a As a number representing the number of seconds since midnight of 
the current day (using the asSeconds instance method) 
m As a three-element array (using the secondClockArray class method) 
■ As part of a two-element array (using the class method 
dateAndlimeNow ) 

B As an instance of class Time (using the class method now) 

One of the big advantages of working with instances of class Time is that 
we can perform a range of calculations, comparisons, and other operations 
on such objects. Considering this, we focus on the now class method. 


Creating the Clock Class 

With the groundwork laid, we can move on to the task at hand. First, 

let’s build the Clock class, which we’ll create as a subclass of Object. 

Here is its class definition: 

Object subclass: #Clock 
instanceVariableNames: 

'sem currentSecond currentMinute currentHour currentDay isRunning 
classVariableNames: '' 
poolDi ctionari es : ' ' ! 
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As you can see, there is a fairly large number of instance variables for 
this class. Four of these instance variables, all starting with the label 
current, store values used in tracking time. The other two instance vari¬ 
ables are isRunning, a Boolean that helps us keep track of when the 
clock is operational and needs to be updated, and sem, a semaphore 
used to control the main multiprocessing block of Clock during clock 
reset operations. 

One instance variable is absent. We might expect to see Clock include 
a variable to hold alarms. However, alarms are actually associated with 
appointments and appointment manipulation is in the capable hands of 
the AppointmentBookWindow and AppointmentBook classes. Rather 
than create a separate collection of alarms, we just modify the Appoint¬ 
ment class to track an alarm state. The Clock object’s responsibility is 
restricted to notifying its owner, the ClockWindow, when a minute has 
passed. The ClockWindow then forwards this notice on to its depen¬ 
dents who are responsible for handling the alarm. You can think of alarms 
as being the knowledge that the appointment needs, while a Clock ob¬ 
ject simply acts as an event generator to let its owner, the ClockWindow, 
know when a certain amount of time has elapsed or a specific time has 
been reached. 

We ve decided to show the clock in the ClockWindow, which is where 
all of our display activity takes place. This facilitates the job of updating 
widgets and managing the display in one class, and promotes the reus¬ 
ability of Clock by removing any requirement for it to deal with display¬ 
ing itself. 

The Clock Class Method 

We need the usual new method, which we call the initialize instance 
method. By the way, you do not need to name this instance method ini¬ 
tialize. You are free to name it anything you like. Here is the method: 

"Return a new, initialized clock" 

A super new initialize. 


Event-Related Instance Methods 

Because we are asking Clock to generate events rather than simply handle 
them, its list of instance methods includes three dedicated to the event¬ 
handling process. All but one of these methods are taken directly from 
other IBM Smalltalk classes. These three methods are: 
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m owner: 
m removeOwner: 
m contents 

The owner, and removeOwner Methods 

The owner: and removeOwner: methods set and remove the owner of the 
Clock, the value of which is stored in the clock object’s dependents col¬ 
lection, which it inherits from the Object class. Here is the code for these 
two methods: 

owner: anObject 

"add an ooject as a requestor" 
self addDependent: anObject.owner: anObject 
removeOwner: anObject 
"remove an object used as a requestor" 
self removeDependent: anObject 

The contents Method 

We use this method to answer the current time kept by the clock. While 
this method is available to an owner it is primarily used internally to 
provide an argument to an event broadcast. Here is the code: 

contents 

"Answers currentSecond as an instance of Time" 

A Time fromSeconds: currentSecond. 

Time Management Instance Methods 

As we mentioned earlier, we have decided to model the operation of the 
Clock object very closely on that of a real-world clock. The main pro¬ 
cessing takes place in the driveGear method, the code for which looks 
like this: 

driveGea r 

"Private - answer the block of code that runs the main drive gear of the 
clock. The block checks the system time, and when one second has passed, 
performs the #second event. The clock can be stopped by changing 
the value 
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of the isRunning boolean to false. When stopped the clock will send 
the event:#off. " 

I sec | 

A [ 

[self isRunning] 

whileTrue: [ 

(((sec := Time now asSeconds) ~= cur rentSecond! or: [sec = 0]) 
ifTrue: [ currentSecond : = sec. 

self broadcast: #second: with: self contents. 
currentSecond = 0 ifTrue: [self resetClock. sem wait], 
self minuteGear. 

] 

]. 

self broadcast: #of f. 

]. 

The comment for this method is largely self-explanatory. Notice that 
we are using a does-not-equal comparison. You might have expected a 
greater-than test. Using the does-not-equal comparison assures that set¬ 
ting time back does not suddenly stop the clock. 

By now you should be familiar with the Object instance method broad¬ 
cast. Here we use its cousin broadcast:with: to notify our owner of the 
event and pass our current contents. Instead of telling the owner a second 
has passed, then having the owner request our contents, we save a step and 
improve overall performance by including this data with the event. 

Another thing the comment doesn’t describe is the part of the method 
which calls resetClock. This happens if the value of currentSecond reaches 
0, which means that when we calculated the current time in seconds 
from midnight, we found we were at midnight. This is the time at which 
we decided to reset the clock, so we do. In the meantime, we put up a 
semaphore to prevent other IBM Smalltalk processes from interfering 
with this update. Here is the code for the sem method, which actually 
posts the semaphore: 

sem 

A sem 

The driveGear method executes quite often, far more than once a 
second. That’s why it must check to see whether a full second has passed 
since its last execution. Every time the method determines that a second 
has passed, it also sends itself the minuteGear message. The minuteGear 
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method then checks to see if a minute has elapsed. Here is the code for 
the minute-managing method: 

minuteGear 

"Test minute, f minute has passed then update curnentMi nute 
send event and hourGean." 

| min | 


((min := cunrentSecond//60) ~= curnentMinute) 
ifTrue: [ curnentMinute := min. 

self broadcast: #minute: with: self contents, 
self hourGear. 

]. 

This method is fairly straightforward. It checks to see if a full minute 
has elapsed and, if so, it sends the ftminute event and then the hourGear 
message. By now, you can see what is happening, so we won’t go into 
detail on the other two time-management methods. Here are the listings 
for hourGear and dayGear : 

hourGea r 

"Test hour, if minute has passed then update currentHour 
send event and dayGear." 

| hour | 


((hour := currentSecond//60//60) ~= currentHour) 
ifTrue: [ currentHour := hour. 

self broadcast: #hour: with: self contents, 
self dayGear. 

I. 

dayGear 

"Test day, if hour has passed then update currentDay 
send event" 

I day j 


((day := Date today dayOfMonth) ~= currentDay) 
ifTrue: [ currentDay := day. 

self broadcast: #day: with: Date today. 

]. 
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Clock Management Methods 

Based on the design and our description of how a Clock object interacts 
with its ClockWindow owner, we can determine that we need methods 
to carry out the following operations: 

h start 
m stop 
■ reset 

m change its state 
m determine its state 

Actually, both starting and stopping the clock involve changing its state. 
Recall that we’ve defined an instance variable called isRunning. Let’s 
use that variable in defining the methods to determine and change the 
state of the clock. Here is the code for the two methods: 

isRunning 

"Get the value of isRunning." 

A isRunning 
isRunning: aBoolean 

"Private - Set the value of isRunning." 
isRunning := aBoolean 

Stopping the clock, then, is a simple matter of sending the isRunning: 
method with an argument of False and broadcasting an off event: 

stop 

"Stop the clock immediately" 
isRunning := false, 
self broadcast: #off. 

Starting the clock is a different matter. We need to start it in a known 
state, so we have to do something to set up such a state. We use the Time 
class method totalSeconds to reset to the current time from the system 
clock. We set the currentMinute and currentHour instance variables from 
the current Second. The currentDay is set using the Date today class 
method. We also broadcast an “on” event for the owner. Notice how the 
block answered by the driveGear method is forked to create an indepen¬ 
dent process. Here’s the code: 
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start 

"Start me running, unless I am already running." 

self is Runring 
ifFalse: [ 

isRunning := true. 

currentSecond := Time now asSeconds. 
currentMinute := currentSecond // 60. 
currertHour := currentSecond // 60 // 60. 
currentDay := Date today dayOfMonth. 

(self driveGear forkAt: Processor 

use^BackgroundPriority) name: 'Drive', 
self broadcast: #on. 

]. 

Finally, here is the code that is called when midnight arrives and the 
clock must be reset to 00:00:00: 

resetClock 

"End of day reset counters to 0" 

currentMi nute := -l."Need to be less then zero so everything fires" 

currentHour := -1. 

[Time now asSeconds = 0] whileTrue: []. "Wait unit1 a second has 
passed" 

sem signal. "Now let everyone go." 

Recall that the gears are activated only when their value changes to 
0. So we define the currentMinute and currentHour instance variables 
as having the value of -1. When they are incremented as part of the way 
the simulated gear assembly works, they will go to 0, which triggers the 
next action. (It turns out we have to do all of this one second late be¬ 
cause we need a second to pass to trigger everything else.) The last line 
of the method releases other processes that may have accumulated dur¬ 
ing the wait. 
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Initializing a Clock Object 

The only thing left to do with a Clock object is to initialize it. Here’s the 
code that handles this assignment: 

initialize 

"Initialize my knowledge" 

isRunning := false, 
sem := Semaphore new. 

As you can see, this method simply turns the clock off and initializes a 
semaphore for use in multiprocessing. 


A Method for Debugging 

It is sometimes wise to provide a printOn: method which will display in a 
Debugger or Inspector the information we are most likely to want to see. 
The method that follows fulfills this requirement: 

printOn: aStream 

"display the clock's current state" 
aStream nextPutAll: 'Clock: ' , currentHour 
printstring,':',currentMinute printstring, ':' , currentSecond 
printString 


Displaying the Clock, the ClockWiidiw Class 

Now that we have a Clock object, we need to develop the ClockWindow 
to take advantage of its availability and display the time. 


The Class Design 

The ClockWindow is nothing but a shell widget and the time is displayed 
as the shell’s title. This makes the window small and provides the time in 
the icon title when it is minimized: 
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11:46:14 PM 


A clock menu might be useful but it would be an aesthetic nightmare, 
not to mention the fact that the window would have to be much larger. 
So we force this menu on another SimplePIM window, probably the 
CalendarWindow class instance. Therefore, we need to “remote con¬ 
trol” the ClockWindow instance. This means all menu operations are 
handled as events. Thus, the new class participates fully in our 
ApplicationController protocol as well as handle clock events. 


instance Variables 

Here is the definition for the new class: 

Object subclass: #C1ockWindow 

instanceVariableNames: 'ac shell clock displayed alarms chime 
cl assVariableNames: ' ' 

poolDictionaries: 'CwConstants CgConstants ' 

The first two instance variables are used to hold an instance of the 
ApplicationController class and the shell widget. The rest of the vari¬ 
ables are described below: 

■ clock, which holds an instance of the Clock class to be connected 
to a specific instance of ClockWindow 

■ displayed , which holds a Boolean indicating the state of the 
window’s visibility 

■ alarms, which holds a Boolean indicating the state of alarm han¬ 
dling 

■ chime , which holds a Boolean that determines if an hourly chime 
should sound 



IBM SMALLTALK 


430 ' 


The Application Controller Protocol Methods 

The first thing we should do is make sure this class is ready to partici¬ 
pate in the protocol we designed in Chapters 8 and 9 for the Application 
Controller. The protocol requires the window to participate in the acti¬ 
vation and closing events. We can simply copy the methods from one of 
the other window classes. The methods required are activate, 
activated:clientData:callData:,controller:, closeWindow.clientData-.call- 
Data, removeActivate, and resetActivate. To make copying easier, you 
may want'to use the global mark and extend mark options we discussed 
in Chapter 15. 

Note: One way to avoid copying a lot of common files is to abstract 
these methods into an abstract superclass. This class would then be re¬ 
sponsible for handling the common protocol for our application win¬ 
dows. This is just another case of design refactoring, which sometimes 
becomes evident only after you have created more than one class. It is 
analogous to slapping your forehead and proclaiming that you could have 
had a vegetable-rich juice. (Of course you’d also need to present this 
abstract class with a name which reflects its high position, a task more 
formidable than copying the methods.) We leave the name and solution 
as an exercise to the reader. 


The Window Control Methods 

We will add two methods to handle two control tasks. The new methods 
are: 


■ clockOff 

■ clockOn 


The clockOff Method 

The clockOff method hides the clock window. To accomplish this task, 
we fall back on the widget structure. Remember that an unmapped wid¬ 
get is an invisible widget. Well, unmapping the shell widget hides the 
entire window: 

clockOff 

"hide me" 

displayed := false, 
shell unmapWidget. 
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The clockOn Method 

Likewise, mapping the shell widget makes the window visible. The clockOn 
method takes advantage of this fact to display the window: 

clockOn 

"Make me visible" 
displayed := true. 
shell mapWidget. 

Notice that both methods track the instance variable display, which 
will be needed later in one of our remote-control methods. 

The Utility Methods 

We will add the following methods: 

b lose, which closes the window, stops the clock, and cleans up 
m open, which creates and opens the shell widget 
B setUp, which initializes all variables to default values, then creates, 
connects to, and starts a Clock instance 

Here is the first of the methods: 

cl ose 

"I've been told to close 
so do any clean up stuff" 
clock stop. 

clock removeOwner: self, 
clock := nil. 
a c := nil. 

shell destroyWidget. 

Now to open the window: 

open 

"open a Clock window and initialize it" 

| main | 

shell := CwTopLevelShell 
createApplicationShel1: 'Starting ...' 
argBlock: [:w | w 

mwmDecorations; MWMDECORALL | MWMDECORMAXIMIZE | MWMDECORMENU]. 
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shell 

addCal1 back: XmNwindowCloseCallback 
receiver: self 

selector: #closeWindow:clientData:callData: 
clientData: nil. 
main := shell 

createMainWindow: 'main' 
argBlock: [:w | w width: 125]. 
main manageChild. 

shell realizeWidget. 
self setup. 

This method requires some explanation. We want the window to be 
as small as possible, so we remove the system menu and maximize but¬ 
tons. We leave the minimize button, however, so that the user can create 
an icon of the window. Next, we control the size of the window by con¬ 
trolling the width of the main window. If the window is still too large for 
you, try a smaller width. While the window and clock are initializing, we 
display the title. This one is quite short compared to the other open meth¬ 
ods we have created. 

And now the last method: 


"create my clock and request clock broadcasts 

displayed := true. 

alarms := true. 

chime := true. 

clock := Clock new. 

clock owner: self. 

clock start. 


setup 
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Event Handling Methods 

Recall that a Clock object can send the ClockWindow object that owns it 
four time-related events, one each for the passage of a second, a minute, 
an hour, and a day. The ClockWindow uses two of the events itself: sec¬ 
ond to update the display and hour to sound the chime hourly. The 
ClockWindow then forwards these events to interested parties through 
its own events. Table 17-1 summarizes the events and their correspond¬ 
ing ClockWindow events. 

Table 17-1. Clock Events and ClockWindow Methods 


EVENT FB0|M C|.0CK METHOD FROM CLOCKWINDOW 


#day newDay: with a Date 

#hour hourlyChime: with aTime 

#rninute checkAlarm: with aTime 

#second clockUpdate: with aTime 


Now to discuss the events from the smallest to the largest units. We 
implement the ClockWindow event handlers as we add them to the appro¬ 
priate class. 

The second: and minute: Methods 

Every second, the ClockWindow object updates the time it displays. This 
is what the clock’s window looks like: 



As you can see, we display the time in seconds, so we need to update it 
every second to keep it current. Here is the code for the second, method, 
which handles the second clock event and forwards it as a clockUpdate 
event. The time supplied to each of these methods and events comes 
directly from the clock. 

second: aTime 

"A second has passed update: the display" 
self updateClock: aTime. 

self broadcast: #cl ockllpdate: with: aTime. 
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This method calls its own method, updateClock:. Here is the code for 
this method: 

updateClock: aTime 

"Display aTime and other appropriate 
symbol s" 

| include | 

clock is Nil ifTrue: [ A self]. 
include := ''. 
a 1 a rms 

ifTrue : [include := include,'*'], 
chime 

ifTrue: [include := include, ' A ']. 
shell title: aTime printstring,include. 

We print the time’s value as a string in the title of the ClockWindow 
instance. In addition to the time, we may need to display two symbols: 

to indicate that alarms are being monitored, and to indicate that 
hourly chimes are active. We first check to see which of these states is 
on, then print the proper symbol(s) with the time. The first line is in¬ 
cluded so that if a widget refresh request occurs before everything is set 
up, an error won’t result. 

The minute: method simply forwards the checkAlarm: event if alarms 
are to be honored. Here is the code for this method: 

minute: aTime 

"A minute has passed broadcast alarm check if applicable" 
a 1 a rms 

ifTrue: [ 

self broadcast: /IcheckAl arm: with: aTime. 

]. 
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The hour :and day :Methods 

Next we have the hour: method, which handles the clock hour event by 
sounding a chime if the hourly chime is on. The method always forwards 
this event as the hourlyChime event. Here is the code: 

hour: aTime 

"An hour has passed 

Sound chime if applicable and send 

event" 

chime 

ifTrue: [OSWidget bel1 ; bel1 ; bel1]. 
self broadcast: #hourlyChime with: aTime. 

To sound the alarm we rely on the OSWidget method bell, which uses 
the host operating system’s default beep. We sound the chime three times 
each hour. (Now you know why we provided the ability to turn it off.) 

Finally, we have the day: method which handles the clock day: event. 
This method has no special task to be performed so it is forwarded as 
the newDay: event. Here is the code: 

day: aDate 

"New day notify dependents” 

self broadcast: #newDay: with: aDate. 

The Remote Control Methods 

By design, the ClockWindow instance is controlled remotely by the Clock 
menu of a CalendarWindow instance. There are four menu items so we 
need four methods to handle the menu tasks. These are the methods: 

a toggleDisplay, which controls whether the ClockWindow is visible, 
using the displayed instance variable 
■ toggleAlarms, which controls whether the ClockWindow honors 
alarms, using the alarms instance variable 
m toggleChime, which controls whether the ClockWindow produces an 
hourly chime, using the chime instance variable 
n restart , which provides a means to reset the clock with the current 
time and date 
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The Toggle Methods 

Let’s begin with toggleDisplay : 

toggle Display 

"Toggle whether to display clock" 
displayed 

ifTrue: [self clockOff] 
ifFalse: [self clockOn]. 

The trick here is the use of the clockOff and clockOn methods. We use 
these methods for two reasons. First, they take care of tracking the dis¬ 
played instance variable. Second, should we decide to change the way we 
hide and display the window, we won’t have to modify this method as well. 
The toggleAlarms and toggleChimes methods are quite similar: 

toggleAlarms 

"Toggle whether to honor alarms" 
alarms := alarms not. 

toggleChime 

"Toggle whether to chime hourly" 
chime := chime not. 

We inverted the Boolean to affect the display. Of course, we need menu 
handling methods for the CalendarWindow object. We will work on these 
methods, as well the menu, later in the chapter. 

The restart Method 

The restart method provides a way to reset the clock with the current 
time and date. Hopefully, it will not be a frequently used method, but it 
provides an alternative to shutting down should a problem arise. The 
method merely stops, then starts, the clock. Here is the code: 

resta rt 

"restart my clock" 
clock stop, 
clock start. 

Those are all of the ClockWindow methods. In the next section we 
will work on adding alarms to appointments. After that, we’ll deal with 
displaying and checking alarms. 
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Alarming Appointments 

In this section, we’ll enhance the SimplePIM application by providing 
the ability to alarm any appointment. When the current time matches an 
appointment’s start time, the bell sounds and a message box appears 
displaying the first 80 characters of the appointment entry. To help the 
user discern an alarmed appointment, the start time of an appointment 
is tagged when it has an alarm set. 

To track alarms we need to add an alarm state to the Appointment 
class. The AppointmentBookWindow object handles alarms in response 
to the ClockWindow event checkAlarm:, which is broadcast once a minute 
by the Clock instance minute event. Any appointment can have an alarm 
set, which means an appointment must not only match the current time, 
but the current date as well. Since appointment dates, as well as the 
current date, are the province of AppointmentBook, we need to modify 
this class as well. 

Adding an Alarm to Each Appointment 

We need a way to determine whether an appointment has an alarm. One 
way to track an appointment alarm is to add an alarm state to the 
appointment’s knowledge base. This means adding an instance variable 
with a Boolean to follow the alarm state. Add a new instance variable 
named alarm to the Appointment class. The resulting definition is dis¬ 
played below: 

Object subclass: #Appointment 

instanceVariableNames: 'start end entry alarm ' 
classVariableNames: '' 
poolDictionaries : ' ' 


IBM Smalltalk all ows us to modify a class' structure even if instances of the class 
exist While this is a convenience over other versions of Smalltalk, it does pose a 
possible problem. Any objects of the class created before the change will have a 
default value of nil in any added instance variables. It is important to keep this in 
mind if you are creating code which assumes a particular value for an instance 
variable, such as a Boolean in our case. A nil is not a Boolean and would result in 
an error. To avoid an error you could check for and avoid a nil, modify an instance 
variable to a new default when a nil is detected, or change all instances using the 
Behavior alllnsiances method. 
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Next, we need to add retrieval and changing methods for new variable: 

alarm 

"returnt my alarm value" 

A a1 a rm. 

alarm: aBoolean 

"set my alarm according to aBoolean" 
alarm := aBoolean . 

The Default Alarm State 

When a new appointment is created, we want the alarm to default to 
“false.” The instance method start:end:entry: sets the appointment data, 
so we need to modify it to set the default alarm state. The new code is 
bolded: 

start: startTimeString end: endTimeString entry: aString 
"set start, end and entry 
alarm := false. 

start := self modifyTime: (self parseTimeString: startTimeString). 
end := self modifyTime: (self parseTimeString: endTimeString). 
entry := aString. 


Discerning an Alarmed Appointment 

By design, an appointment’s start time is displayed with a tag if an ap¬ 
pointment has an alarm set. The question is, who should do the tagging? 
The Appointment class already has the responsibility of providing dis¬ 
play strings for an appointment’s start and end times. Perhaps we should 
include the alarm tag as part of the start time display. This would result 
in a consistent time display, allow the class to decide which character to 
use and, more importantly, save other objects the pain of modifying then- 
code to accommodate the tag. Here is the modified displayStartTime method: 

displaySta rtTime 

"answer start in display format" 

A (self displayTimeString: start), 

(alarm ifTrue: ['*'] 
ifFalse: [’’]). 
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This method employs a small trick which takes advantage of Smalltalk’s 
interpretation of a statement. The code within the parentheses is inter¬ 
preted first and results in one of two strings, which is then concatenated 
to the display string. We have decided to use an asterisk “*” as the alarm 
tag to be consistent with the alarm tag we chose for the clock display. 

A Sticky Wicket 

Now that we’ve provided a tagged display, we must match a tagged time 
string. The matchStart: method takes a time string to compare to the 
receiver’s start time. This process requires the time string to be parsed 
into a time. It is likely the time string passed to the method is the display 
string we provided, and it is tagged. So we need to modify the 
parseTimeStrmg: to handle a tagged time string. The code for the changed 
method follows: 

parseTimeString: a St ring 

"answer a time created from aString in the h:m am/pm format" 

| time hour minutes pm size string] 

string := aString last = $* "First remove alarm set character" 
ifTrue: [aString copyFrom: 1 to: aString size - 1] 
ifFalse: [ aString]. 

time : = string asllppercase substrings: $:. 
hour : = ( t*'me at: 1) asNumber. 
time size == 2 

ifTrue: [ time := time at: 2. 

minutes := time asNumber] 
ifFalse: [time :=* time at: 1. 
minutes := 0]. 
size := time size > 1 
ifTrue: [time size - 1] 
ifFalse: [time size], 
pm := ( time at: size) = $P. 
pm ifTrue: [ hour := hour + 12]. 

A Time now hours: hour minutes: minutes seconds: 00. 

The solution to this dilemma is actually quite simple. We remove the 
tag before trying to parse the string by testing the last character. If it is 
a tag, we create a copy of the string minus the last character. If it’s not a 
tag, we pass on the original string. 
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Checking for Alarms 

Now that appointments have alarms, we need to determine how and when 
to recognize them. For this we turn to our AppointmentBookWindow and 
AppointmentBook classes. It will be their combined responsibility to deter¬ 
mine whether an alarm has occurred and, if so, to display the alarm mes¬ 
sage box. The division of labor results in AppointmentBook detecting an 
alarm occurrence and AppointmentBookWindow dealing with the UI and 
event handling. Let’s operate on the AppointmentBookWindow class, which 
should help determine how best to interface with the AppointmentBook 
class. 

Handling the checkAlarm: Event 

According to protocol, to participate in an event, the Appointment- 
BookWindow is required to implement an event method, in this case 
checkAlarm: . This method takes one argument, the current time ten¬ 
dered by the clock. This is a busy method (probably a candidate for 
refactoring in the future). When it has determined that an alarm has 
transpired, it displays up to 80 characters from the given appointment’s 
entry in an alarm message box. It then resets the appointment’s alarm 
state and refreshes the appointment list. Here is the method: 

checkAlarm: aTime 

"check to see if today's Schedule 
has an appointment of aTime, display alarm if set" 

| appt message | 

(appt := apptBook checkAlarm: aTime) isNil 
i f F a 1 s e : [ 

OSWidget bel1 . 

message := appt entry size > 80 

ifTrue: [ appt entry copyFrom: 1 to: 80] 
ifFalse: [ appt entry]. 

CwMessagePrompter new 

messagestring: message; 
buttonType: XmOK; 

title: 'Your Scheduled Appointment for:'; 
prompt. 

appt alarm: false. "Turn off alarm" 

self dateChanged: apptBook currentDate "Refresh list". 

]. 
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This code should all be familiar. The only point of interest is the last 
line, where we use our own event method to indicate a date change to 
refresh the appointment list. 

This method has also raised the requirements for an AppomtmentBook 
instance method. It must answer either an appointment or nil and take 
a time. The method checks the time against today’s scheduled appoint¬ 
ments. If an appointment start time matches the given time and has an 
alarm set, it answers the detected appointment, otherwise it returns nil. 
The new method’s code follows: 

checkAlarm: aTime 

"answer nil or appointment for aTime" 

I appt | 

appt :=self appointmentsAt: Date today, 
appt notNil 

ifTrue: [appt := appt detect: [:a | a start = aTime] ifNone: 
[nil] J* 
appt is Nil 
i fTrue : [ ,N ni 1 ] 
ifFalse: [ A appt alarm 
(fTrue: [ A appt ] 
ifFalse: [ A ni1 ] ]. 


Setting Appointments 

We’ve been so preoccupied with the detection of the alarm that we al¬ 
most forgot about providing a way for the user to set and reset appoint¬ 
ment alarms. The AppointmentBookWindow already provides the UI 
for creating, deleting, and displaying individual appointments. We can 
take advantage of this and add a menu choice for toggling the alarm 
state of the selected appointment. This is a shared task; however, this 
time the AppomtmentBook is doing most of the work. 

Changing the Alarm State of an Appointment 

This time we work in the opposite direction, starting with the 
AppomtmentBook class. The toggleAlarm method simply takes the cur¬ 
rent appointment pointed to by the currentAppt instance variable and 
toggles its alarm state. If no appointment is selected, it does nothing. 
Here is the method: 
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toggleAla rm 

"answer current appointment alarm or nil" 
currentAppt isNil 

ifTrue : [ A ni1 ] 

ifFalse: [ A currentAppt alarm: currentAppt alarm not]. 


The Toggle Alarm User Interface 

The AppointmentBookWindow class requires that we add one method 
and modify another method to fill out the UI. The new method handles 
a new menu item and is called alarm:clientData:callData:\ 

alarm: widget clientData: ignore callData: data 
"User want alarm of current appt 
toggled" 

I appt | 

apptBook toggleAlarm. 

self setSchedule: apptBook getCurrentDaySchedul e. "Refresh the list" 

Notice this alarm uses a slightly different approach to refreshing the 
appointment list. Either way is legitimate. Now on to the addMenuBar: 
method, which adds one more menu item. Since the method is so long, 
we display only a segment of the code to help you locate the changes, 
which are in bold: 

item := form2 

createPushButton: 'Save' 
argBlock: nil. 

item addCallback: XmNactivateCal 1 back 
receiver: self 

selector: #save:clientData:callData: 
cl ientData : nil. 
item manageChi 1 d. 

item := form2 

createPushButton: 'Toggle Alarm' 
argBlock: nil. 

item addCallback: XmNactivateCal 1 back 


receiver: self 
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selector: #alarm:clientData:call Data: 
clientData: nil. 


i tern 

manageChi1d. 



i tern 

:= form2 




createPushButton: 

; 'Today' 


argBlock: 

nil . 


i tern 

addCa11 back: 

XmNact 

ivateCallback 


receiver: 

self 



selector: 

#today: 

:clientData:ca 


clientData 

: nil. 


i tern 

manageChi1d. 




That’s all there is to adding alarms. In the next section, we will modify 
the CalendarWindow class to provide the user with the ability to control 
the ClockWindow remotely. 


Remotely Controlling a Window 

We’ve already created the methods which control the ClockWindow it¬ 
self. What we have left to do is create a Clock menu and its correspond¬ 
ing methods in the CalendarWindow class. 

The Clock Menu Interface 

We decided it was best to make the menu method a separate method 
rather than add all the items to the addMenuBar: method. Here is the 
clock menu method: 

clockMenu: menuBar 

"create the clock menu" 

| form subMenu item | 

form := menuBar createPul1downMenu: 'pulldown' 
a r g B1o c k: nil. 

subMenu:=menuBar createCascadeButton: 'Clock' 
argBlock: [:w| w subMenuId: form]. 
subMenu manageChild. 


item := form 

createPushButton: 'Toggle Display' 
a rg B1ock : nil. 
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item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #clockDisplay:clientData:callData: 
clientData: nil. 
item manageChi1d. 

item := form 

createPushButton: 'Toggle Alarm' 
argB1ock: nil. 

item addCallback: XmNacti vateCal 1 back 
receiver: self 

selector: #clockAlarms:clientData:callData: 
clientData: nil. 
item manageChild. 

item := form 

createPushButton: 'Toggle Chime' 
argB1ock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #clockChime:clientData:cal 1 Data: 
clientData: nil. 
item manageChi1d . 

item := form 

createPushButton: 'Restart' 
argB1ock: nil. 

item addCallback: XmNactivateCal1 back 
receiver: self 

selector: #clockRestart:clientData:callData: 
clientData: nil. 
item manageChild. 
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Of course, we need to link this method to the addMenuBar: method. 

Add the following code to the end the addMenuBar: method: 

self clockMenu: menuBar. 

Now let’s write the methods to handle each menu item. These meth¬ 
ods simply make a request of the ClockWindow, which calls itself #Clock, 
through the Application Controller. The methods are exactly the same 
except for their requests. Here are all the methods as they are listed in 
the menu method above: 

clockDisplay: aShell clientData: clientData callData: callData 
"Inform clock to toggle display thru 
clock request." 

| answer | 

ac request: #toggleDisplay from: #cloek. 

clockAlarms: aShell clientData: clientData callData: callData 
"Inform clock to toggle alarms thru 
clock request." 

| answer | 

ac request: #toggleAlarms from: #clock. 

clockChime: aShell clientData: clientData callData: callData 
"Inform clock to toggle chime thru 
clock request." 

| answer | 

ac request: #toggleChime from: #clock. 

clockRestart: aShell clientData: clientData callData: callData 
"Inform clock to toggle display thru 
clock request." 

| answer | 

ac request: #restart from: #clock. 
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Application Controller Methods 

We need to modify the Application Controller launch method to include 
the ClockWindow object. This means setting the new application and 
adding interest to it for the existing applications. Here is the new launch 
method with changes in bold: 

launch 

"launch the applications I control. Each Application to be opened 
should appear here" 

|a p p1 app2 app3| 

"assign keyword to each application" 

appl := self setAppl i cati on : #Ca 1 enda rWi ndow type: //Calendar . 
app2 := self setAppl i cat i on : //Appoi ntmentBookWi ndow 
type: //Appoi ntmentBook. 

app3 := self setAppl i cati on: //ClockWindow type: //Clock. 

"ready to launch all apps, open is assumed to be the starting 
method" 

self startApplications. "Starts all apps" 

"finally set up each apps dependency framework" 
self application: appl has Interest InTypes : //(Appoi ntmentBook Clock), 
self application: app2 has InterestlnTypes: //(Calendar Clock). 

Notice that we have used a new version of the application:has- 
InterestlnType: method. The new method takes a collection instead of a 
single symbol. Here is the code for this method: 

application: anApp hasInterestlnTypes: aCollection 
"add application as a dependent of the 
application appType" 

I app | 

aCollection do: [: appType | 

app := self getApplicationOfType: appType. 
app not Nil ifTrue: [ 
app addDependent: anApp 

]. 
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Testing the Finished Application 

The new ClockWindow classes and all our modifications to other classes 
are now ready for testing with our new multiprocessing Clock object. 
Try adding an appointment for a few minutes from now and toggle its 
alarm. Then continue working and ensure that the alarm sounds as it 
should. You can move around inside the calendar, checking out appoint¬ 
ments and holidays. Test the Clock menu items and see if the display 
reflects your requests. See if the clock is active with the other windows 
open and closes with the rest of the application. 

We should point out that you have been able to accomplish the cre¬ 
ation of a reasonably capable calendaring program with an appoint¬ 
ment book and an alarm clock while only having to write a few hundred 
lines of new c ode. This same feat would require thousands of lines in a 
non-OOP language environment without IBM Smalltalk’s powerful built- 
in class library. You should be feeling pretty good about yourself! 



You didn’t expect us to let you off the hook quite that easily, did you? As 
useful and powerful as this application is, it still lacks a few features 
we’d like to add. So we’re going to take one last pass through it to do the 
following: 

h Add support for handling the newDay: event 
h Add support for saving and loading appointments with alarms 
b Create a new version of the clock which uses separate forked pro¬ 
cesses for each gear 


A Mew Day for the Calendar 

When the clock reaches midnight it signals a day event which is for¬ 
warded to interested parties by the ClockWindow as the newDay: event. 
We could use this event to set the Calendar and Appointment Book to 
the next day; all we need is one method to handle the event. The new 
CalendarWindow instance method is called newDay:: 
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newDay: aDate 

"Event handler, new day 
so set calendar to today" 

self today. 

The method simply calls the today method which sets into motion all 
the updates necessary to click over to a new day and its scheduled ap¬ 
pointments. 


Resolving a Storage Problem 

Next on our agenda is the storage and retrieval of appointments again. 
When we last dealt with this problem, we had decided to let the Ap¬ 
pointment object handle these tasks itself. A wise choice indeed (and 
you knew it would be). Now, including the alarm state in our external 
storage is simply a matter of changing two Appointment instance meth¬ 
ods. The two instance methods to change are storeTo: and restoreFrom:. 
(By the way, the restoreFrom: class method does not need to be changed.) 
The only question is, how should we store a Boolean object? We could 
use strings of “true” and “false” or “1” and “0.” We will use 1 and 0 to 
save space in our files (since we know they’ll grow very large with use). 
Here is the storage method revised (new code in bold, as usual): 

storeTo: aStream 

"store object information on aStream separated by delimiters" 

| del objDel| 

del := (Character value: 255). 
objDel := (Character value: 254). 
aStream 

nextPutAl1: self displayStartTime; nextPut: del; 
nextPutAll: self displayEndTime; nextPut: del; 
nextPutAll: entry; nextPut: del; 
nextPutAl1: (alarm 

ifTrue: ['1'] 
ifFalse: [’O']); 
nextPut: objDel. 

That was easy. Now for the restore method (remember, we’re editing 
the instance method): 
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restoreFrom: aStream 

"restore object data from a stream separated by del delimiters" 

| del objDel objectData | 

del := (Character value: 255). 

objDel := (Character value: 254). 

objectData := aStream upTo: objDel. "get all obect data" 

objectData := objectData substrings: del. "now parse each data 
item and assign" 

self start: (objectData at: 1) end: (objectData at: 2) entry: 
(objectData at: 3). 

alarm := ((objectData at: 4) asNumber) = 1. 

A self. 

Here we simply add a line of code which translates the array item, 
aString, into a number and finally back into a Boolean. (Yes, all that on 
one line). It is a credit to our design that we don’t have to worry about 
array size changes and index manipulation. 


But what of the old appointment files (*.apt)? Are they compatible? What should be 
done with them? Mo, they are not compatible and because this is an ongoing 
development process, we can delete them. In the real world, we would have to 
consider this issue a little more seriously. We would either provide backwards 
compatibility, supporting both sets of files, or create a conversion process. The 
former requires that we find some way to distinguish the files, and the latter 
necessitates an additional user interface. The solution is left as an exercise and test 
of your creativity. 



A Super Duper, New and Improved Clock 

One question you may have asked yourself is this: If IBM Smalltalk sup¬ 
ports multi-processing, why did we decide to fork only the gear process 
and make the other gears mere methods? Glad you asked. We are about 
to remedy that situation by turning all of the gears into forked processes. 

Actually, forking the processes is easy—we simply turn the methods 
into blocks and fork them. The real challenge is in handling multiple 
semaphores. Each gear is responsible for at least two semaphores: its 
own, which it waits on, and the next gear’s semaphore, which it signals. 
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The interface between the drive gear and the minute gear is a little 
more complicated. The minute gear is required to deal with three sema¬ 
phores: its own, the next gear’s, and the drive gear’s. Why the drive 
gear? If we let the drive gear loop around willy-nilly, it builds up a series 
of semaphore signals to the minute gear, which is not good at all. With a 
backload of signals, the minute gear never waits on its semaphore, and 
all the gears above are misaligned as well. By making the drive gear 
wait for the minute gear, spurious signals are not generated and every¬ 
thing runs smoothly. 

We create the new clock by creating a subclass of Clock called Clock2. 
Subclassing allows the new clock to participate in the existing structure. 
We only need to be concerned with the gear methods and setting up the 
extra semaphores. 

The Newly Ground Drive Gear 

Without further ado we present the new gear, with differences from its 
superclass method boldfaced: 

driveGear 

"Private - answer the block of code that runs the main drive gear of 
the clock. 

The block checks the system time, and when one second has passed, 
performs the //second event. The clock can be stopped by changing the 
value of the isRunning boolean to false. When stopped the clock will 
send the event://of f. " 

I sec | 

A [ 

[self isRunning] 
whileTrue: [ 

(((sec := Time now asSeconds) ~= currentSecond) or: [sec = 0]) 
ifTrue: [ currentSecond := sec. 

self broadcast: //second: with: self contents. 
currentSecond = 0 ifTrue: [self resetClock. sem wait]. 
sem2 signal . 
sem wait. 

]. 

]. 

self broadcast: //off. 

]. 
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As expected, this is just one large block with two loops. All we did 
here was replace the call to the minute with signal and wait messages to 
semaphores. 

The blew Minute Gear 

As we discussed, the minute gear is a little more complicated. Here is its 
code: 

minuteGear 

"Test minute, if minute has passed then update currentMinute 
send event and hourGear." 

| min | 


A [ [s e1f is Running ] 
whi1eTrue: [ 

((min := currentSecond//60) ~= currentMinute) 
ifTrue: [ currentMinute := min. 

self broadcast: #minute: with: self contents. 
sem3 signal . 

]. 

sem signal. 
sem2 wait. 

1. 

]. 

Besides encasing the method inside a block, we added some semaphores. 

The Mew Hour Gear 

Here is the hour gear’s code: 

hourGea r 

"Test hour, if minute has passed then update currentHour 
send event and dayGear." 

| hour | 


A [[self isRunning] whileTrue: [ 

((hour := currentSecond//60//60) ~= currentHour) 
ifTrue: [ currentHour := hour. 

self broadcast: #hour: with: self contents. 
sem4 signal. 
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]. 

sem3 wait. 

] 

]. 

There are no surprises here. 

The New Day Gear 

The day gear looks similar to the hour gear but does not have any sema¬ 
phore to signal. Here is the code: 

dayGear 

"Test day, if hour has passed then update currentDay 
send event" 

I day | 


A [[self isRunning] whileTrue: [ 

((day := Date today dayOfMonth) ~= currentDay) 
ifTrue: [ currentDay := day. 

self broadcast: #day: with: Date today. 

]. 

sem4 wait. 

]. 

]. 

The Clock! Utility Methods 

While the gears represent the major code changes for this class, we do 
need to modify a few more support methods. With the gear methods, the 
nature of blocks and the code made it impossible to create overriding 
methods, so basically the methods are modified copies of their super¬ 
class counterparts. The support methods, on the other hand, do repre¬ 
sent class specialization and can override the superclass methods. Here 
are all three methods: 

initialize 

"Initialize my knowledge" 
super initialize. 
sem2 := Semaphore new. 
sem3 := Semaphore new. 
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sem4 := Semaphore new. 
start 

"Start me running, unless I am already running." 
super start. 

(self minuteGear forkAt: Processor userBackgroundPriority) name: 

'Minute'. 

(self hourGear forkAt: Processor userBackgroundPriority) name: ’Hour’, 
(self dayGear forkAt: Processor userBackgroundPriority) name: 'Day' . 

stop 

"Stop the clock immediately" 

super stop. 

sem2 signal . 

sem3 signal. 

sem4 signal. 

As you can see, each of the methods simply extends the work of its 
superclass method to add support for additional semaphores or pro¬ 
cesses. The stop method is the only method which differs from its super¬ 
class method; after stopping the clock, it releases each of the gear pro¬ 
cesses which may be waiting on the indicated semaphore. This makes 
sure the processes are collected as garbage and don’t hang around in 
the image like unwanted house guests. 

So there you have it, the new clock and more power without a lot of 
code. All that remains is to hook up the new clock to the existing 
ClockWindow class. This is relatively easy. In the ClockWindow instance 
method setUp, change the class reference from Clock to Clock2. 

Anther Test of Time 

Launch the SimplePIM application and see how the new clock integrates 
with the existing scheme. At first, you won’t notice any difference, but as 
time goes by, you’ll notice that there are no longer any delays. Although 
we kept our code very compact in the first clock, occasionally it would cause 
a delay in Smalltalk processing. The new clock no longer exhibits these 
hesitations. See if you can store and retrieve appointments and make sure 
the alarm state is retained as well. Don’t forget to watch for a new day. If 
you prefer not to wait until midnight, just change the system time. 





API Application Program Interface, the means by 

which a DLL or another program designed for use 
by application programming tools can be accessed 
and controlled. 

Block A portion of a method enclosed in square brack¬ 

ets and treated as a single statement. Blocks are 
used in loops and conditional expressions to pro¬ 
vide a single argument to be executed repeatedly 
or conditionally. 

C++ The object-oriented version of the C programming 

language. C++ is the object-oriented language in 
widest use today. Many people see C++ as a dif¬ 
ferent language from C, while others, including 
the authors of the present volume, consider it an 
extended C with all the advantages and disadvan¬ 
tages implied by that observation. By contrast, see 
Objective C. 

Cascading The technique of sending several consecutive mes¬ 

sages to the same object without repeating the 
name of the object. Each successive statement ad¬ 
dressed to the object is separated from the others 
in Smalltalk/V for Windows by a semicolon rather 
than the usual statement-terminating period. A 
period then indicates the end of the cascaded 
message group. 


Class 


Class variable 


DDE 


DLL 


Encapsulation 


Inheritance 


Instance 


A construct common to all object-oriented pro¬ 
gramming languages and systems. Serves as a 
vehicle for collecting common behaviors into a 
single object template from which other objects 
can be created as instances and from which other 
classes can be derived by subclassing. 

A variable associated with and shared by all in¬ 
stances of a class. Both the variable itself and its 
value is the same across all instances of a class. 
Contrast with instance variable. 

Dynamic Data Exchange, a Microsoft-initiated pro¬ 
tocol for interapplication communication. Using 
DDE, a program called a client establishes a com¬ 
munications link with another program, called a 
server, and sends the server commands, data, and 
requests, to which the server responds if possible. 

Dynamic Link Library, a Microsoft Windows pro¬ 
gram type. A DLL is a collection of related code 
stored on the user’s disk. They can be loaded when 
needed by any program capable of calling them. 
Both Smalltalk^ for Windows and applications 
written in this environment can use DLLs. 

The concept of combining data and methods in a 
single object. One of the three main ideas in ob¬ 
ject-oriented programming. The others are in¬ 
heritance, and polymorphism. 

The process by which a class receives traits ( in¬ 
stance variables, class variables, and methods) 
from a class which is above it in the Smalltalk/V 
for Windows class hierarchy. One of the three main 
ideas in object-oriented programming. The oth¬ 
ers are polymorphism and encapsulation. 

A specific manifestation of a class. When a class is 
used as a template for creating a specific example 
of an object, the resulting object is an instance of 
the class identified with the object. The word object 
sometimes refers to a specific instance, as in the 
phrase “a Window object,” which could be phrased, 
“an instance of the class Window.” 



Instance variable 


Message 


Method 


Object 


Object-Oriented 


Objective C 


A variable value associated independently with 
each instance of a class. All instances of a given 
class have a common set of instance variables, 
but each instance generally assigns its own val¬ 
ues to these variables. Contrast with class vari¬ 
able. 

The means by which objects communicate with 
one another. Objects send and receive messages. 
An object can only respond to a message sent to it 
if it contains or inherits a method of the same name 
as the message. 

A single collection of program statements to be 
executed by the object to which the method be¬ 
longs whenever that object receives a message of 
the same name as the method. 

A software construct that combines data and pro¬ 
cedures ( methods ) that operate on the data into a 
single container. Objects are at the heart of ob¬ 
ject-oriented programming. Objects communicate 
with other objects in an application or system by 
sending and receiving messages. 

A much-abused term. Purists argue that the term 
should be limited to programs and tools that sup¬ 
port completely the notions of encapsulation, in¬ 
heritance, and polymorphism. That definition 
clearly applies to Smalltalk. Others prefer a less 
stringent definition that permits inclusion of pro¬ 
grams supporting one or two of these ideas or that 
provide some similar benefit. Applications such 
as drawing programs that use objects that cannot 
be subclassed and graphical user interfaces that 
use things like windows are definitely not object- 
oriented. 

A version of the C programming language modi¬ 
fied and extended to include objects. Unlike C++, 
Objective C was designed from the ground up to 
be object-oriented while taking advantage of some 
of the power inherent in C. Objective C is best 
known for its use on computers from NeXT, Inc. 
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00 A 
00D 
OOP 
Pane 


Polymorphism 


Subclass 


Variable 

Window 


Object-Oriented Analysis. 

Object-Oriented Design. 

Object-Oriented Programming. 

A rectangular portion of a window dedicated to a 
specific purpose or capable of displaying a spe¬ 
cific type of information. 

The idea that two or more types of objects , or two 
or more classes , can respond to the same mes¬ 
sage in different ways. One of the three main ideas 
in object-oriented programming. The others are 
inheritance and encapsulation. 

A class derived by inheritance from another class. 
The process of creating a class this way is called 
“subclassing.” In Smalltalk/V for Windows, all 
classes are subclasses with the single exception 
of the root class called Object. 

See instance variable and class variable. 

A rectangular area of the screen in which all in¬ 
formation displayed to the user is framed. 



Special Characters 

# preceding argument to selector: portion of 
message registering callback, 109 
@ message to create a new point, 268 
I enclosing temporary or local variables, 27 
$* and $? wildcards to search directories, 373 

A 

AfotCLBTAdditions sub application, object- 
management methods of, 66 
AdditiveSequenceableCollection class, 45 
defined by CLDT subapplication, 30-31 
Alphanumeric characters, method for checking 
for, 141 

Angle brackets on buttons, 146-47 
Animation, Debugger option to watch each step 
of process for, 18-19 
Application. See also Projects, sample 
creating new, 78-81 
initializing, 82 
multi-window., 175-80 
runtime, flat object storage or persistent 
object storage for, 379 
Application Browser 

creating new application using, 78-79, 116 
opening, 52, 117 

Application development using IBM Smalltalk 
adding methods during, 73 
beginning, 61 
class diagrams in, 64-65 
creating abstract classes in, 70-71 
creating objects in, 65-68 
deciding what application should do in, 61-62 
listing objects and their responsibilities in, 61, 
62-63 

modifying classes in, 68-69 
Application Manager, creating new applica¬ 
tion in, 52 

Application Manager window, displaying, 52 
ApplicationController class, 222-30, 307 
in Appointment Book sample project, 179-82, 
182-83, 222-30, 307 
defining, 223 

dependency framework of, 222, 223-26 
to launch and manage applications, 181 


multiple windows managed by, 228 
in multiprocessing application, 429-30 
responsibilities of, 180, 222 
synchronization and data update 
processes in, 183 
Applications menu 

Application Browser opened using, 53 
creating a new application using, 52 
Applications essential to using IBM Smalltalk, 
28-37. See also individual applications 
Applications list in browser, 7 
Appointment Book sample project, 179-249 
accessing appointments in, 191-93 
adding event messages to, 233-36 
ApplicationController class in, 179-80, 183, 
222-30, 307 

background color in, 248 
callbacks for, 221, 238-39 
cutting, copying, and pasting appointments 
in, 182, 238 

debugging trick for times in, 188 
dependent objects in, 222 
display methods for, 189-90 
displaying day’s schedule in, 192-93 
enhancements to, 249 
entering appointments in, 196 
framework of, 222-40 

generating label string for Appointment Book 
window in, 197 

getting appointments for given date in, 
195-96 

highlighting in, 181-82, 203-205, 243 
holiday descriptions for, 237-38 
holiday entries by user for, 239-40 
initialization method in, 191-92 
instance creation method in, 192 
as integrated with Calendar application, 
181-82 

menus in, 181-82, 216-22, 240, 240-42, 307 
methods requesting information in, 226-27 
multiple windows supported in, 182-83, 222, 
228-30 

open method for, 205-7, 231 
refreshing appointment list in, 216, 244 
retrieving schedule in, 191-92 
saving appointments in, 182, 196 
selecting appointments from collection in, 190 
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ApplicationController class (continued) 
setting up, 183 

sorting appointments in, 194-95 
synchronization issues in, 228-30 
testing, 188-89, 202-3, 242-48 
user operations in, 181-82 
utility methods in, 190, 197-98 
widget placement for, 207-15, 221 
Appointment class 
adding alarm to, 437-39 
created in Appointment Book application, 
185-90 

extended in file input/output project, 381, 
383-86 

Appointment method, 185-86, 193 
AppointmentBook class 
created in Appointment Book application, 
190-198 

detecting an alarm occurrence using, 440 
extended in file input/output project, 381, 
386-92 

setting appointments using, 441-42 
AppointmentBookWindow class, 238, 307 
accepting collection and asking for size of 
appointments in, 210 
adding instance variables to, 205-6 
changing, 205-222 
creating a plot class instance in, 308 
event messages broadcast from, 233 
extended in file input/output project, 391-92 
file input/output for, 381, 385 
files opened and closed in, 391 
menu bar for, 240-41 

modifying the open method for, 205, 206-7 
returning to today’s appointments through 
inter-application communication with, 
240-42 

UI and event handling handled by, 440-41, 
442-43 

widget tree for, 207-9 

Array class defined by CLDT subapplication, 
30, 31 

ArrayedCollection class defined by CLDT 
subapplication, 31 

ASCII characters, defining behavior of, 33 
Association class defined by CLDT 
subapplication, 30, 32 

B 

Bag class, 43 

defined by CLDT subapplication, 30-31 


Behavior class defined by Core subapplication, 30 
Binary selector, 25 
Bitmap defined, 255 
Block class in Core subapplication, 30 
Boolean class defined by CLDT subapplication, 
30-31 

Browser. See also Application Browser, Change 
Log Browser, and TrailBlazing Browser 
(TrailBlazer) 

Change Log, 10-11 
choosing, 3-7 
class, 12-13, 118, 184 
classes removed using, 9-10 
default lists in, 7-8 
method, 13 
opening new, 7 
standard, 3-4 
templates in, 8-9 

Busyness Indicator application, 335-58 
building the project for, 337-58 
Busyness Chart in, 308, 335-37 
copying methods for, 339-40 
designing application for, 335-36 
ExtendedBusynessWindow chart for, 337, 
340-46, 350, 357-58 

ExtendedBusynessWindow class in, 338, 346 
fonts for, 340, 350-54 
general approach of, 336-37 
knowledge needed for, 337 
menus in, 339, 346, 357-58 
overview of, 335 
rotating bars in, 346-49 
superclasses of, 336, 337-40 
testing, 346, 350, 354-5 
text widget in, 336-37, 338-40 
Busyness Window class 
added to the SimplePIM framework, 307-8 
to create a collection of dates, 305-7 
replacing reference to, 346 
subclassing, 336-337 

c 

Calendar class, 135-40 
behaviors of, 135 

changed by Appointment Book sample 
project, 198-201 
definition of, 136 
information in, 135 
initialization routines for, 136-37 
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Calendar sample project, 115-74 
adding color to, 158 

adding menu equivalents to buttons in, 160-66 
application design of, 116 
application setup for, 116-18 
Appointment Book application integrated 
with, 180 

button attachment for, 153-54 
changed to respond to user’s button press 
event to select appointments date, 202-3 
creating CalendarWindow application in, 
145-58 

Date class for, 118-22 
defining Calendar class for, 135-40 
displaying today’s date in, 160 
highlighting special dates in, 158,159-60, 173 
incrementing and decrementing months and 
years in, 137-40 

menu bar modifications for, 219-21 
methods to handle navigation in, 167-68 
methods to handle requests in, 236-37 
moving to specific date in, 168-69 
open method for, 146-56, 231 
prompter for the date created for, 170 
rowColumn widgets attached to each other in, 
154-55 

setLabel and setUp methods in, 157 
synchronization of two windows in, 175 
testing, 170-74 
tools for, 124-34 

updating (refreshing) in, 166, 202-3 
windows for, 147-52 
CalendarWindow class, 308 
creating application using, 145-58 
menu bar method in, 216-18 
messages broadcast for, 233-34 
request message methods added for, 

236-37, 241 

callback message protocol to handle actions in 
IBM Smalltalk, 93 
Callbacks 

assigned in open method, 93 
to define application’s response to events, 
107-8 

example of triggering, 109 
methods as, 167 
multiple, 110 
registering, 108 

Carriage return line feed (CR/LF), 360 
Cast members for a method, 141 
CfsConstants pool dictionary, 360 


CfsDirectoryDescriptor class 
to change, create, and remove directory, 
371-72 

wildcard characters to search directories 
using, 373 

CfsDirectoryEntry class to provide instance 
methods for filename, 371-72 
CfsError class, file variable of, 363 
CfsFileDescriptor class, 363 
CfsFileStream class 

created by CfsStreams subapplication, 37 
hierarchy of, 362-63 
support for creation of streams by, 362 
CfsReadFileStream class 
for creating read-only streams, 37 
message for overwriting file not responded to 
by, 363 

support for input of data by, 362 
CfsReadWriteFileStream class 
for creating read/write streams, 37 
support for input and output of data by, 362 
CfsStat class 

to access file statistics, 371-72 
support across platforms for, 372 
CfsStreams subapplication, 37 
CfsWriteFileStream class 
for creating write-only streams, 38 
for opening a file, 391-92 
support for output of data by, 362 
CgCharStruct class, font characters repre¬ 
sented in, 323, 325 
CgConstants pool dictionary, 253 
CgDisplay class 

font-loading process using, 329 
forming link to application, 253 
CgDrawable class 

created by Common Graphics application, 35 
drawing and graphics display controlled by, 
252, 254-55, 259-60, 341 
multiple text strings drawn by, 323 
point displayed within instance of, 268 
CgDrawingArea widget for freeform drawing 
area, 255 
CgFont class 

as center of font object composition, 323-24 
created by Common Graphics application, 36 
CgFontProp class, font name included in, 325 
CgFontStruct class 
composition of, 323, 326 
created by Common Graphics application, 36 
font characteristics described by, 324, 342, 
352-53 
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CgGC class (GC) 
assigning fonts to, 331 
color in, 344 

copying attribute values using, 258 
created by Common Graphics application, 36 
drawing performed by sending message to 
window using, 253, 341 
freeing resources of, 258 
as graphic context, 283 
information contained in, 255 
key to working with, 256-58 
loaded font given to instance of, 329 
modified attributes for, 256-57 
representing a graphics context, 252 
retrieving value from, 258 
CgGCVAlues class 
for attributes masked, 256 
to provide value storage, 255 
CglndexedPalette class, pixel value indexed 
to, 266 

CgLogicalFontDescription class in specifying 
and parsing font names, 323-24, 325-27 
CgPixmap class, drawing operations per¬ 
formed using, 254, 255 
CgRGBColor class, 132 
in Appointment Book application, 202-3 
in Calendar application, 158 
for graphic images, 264-65, 295 
CgScreen class 

created by Common Graphics application, 36 
physical graphics display handled by, 

254,255 

CgTextltem class 
to draw multiple text strings, 323 
methods to set, 331 
serving as data structure, 328 
CgWindow class 

created by Common Graphics application, 35 
drawing in a window using, 252-54 
as window object, 254 
Change Log Browser, purpose of, 10-11 
CHANGES.LOG file (Change Log) 
purpose of, 10-11 
reducing size of, 12 
Character class defined by CLDT 
subapplication, 30, 33 
children method, 132 
Class(es). See also individual names 
abstract, 29, 70-71 
accidental deletion of, 9 
concrete, 70 


defining, 78 

essential for using IBM Smalltalk, 28-29 
identifying the right, 71 
methods added to, 73-74 
modifying behavior of, 68-69 
removed using the browser, 9-10 
saving, 97 
subclassing, 67 

template for defining new, 8-9 
Class class defined by Core subapplication, 30 
Class definition 
adding comment to, 26 
of classes used to store information in data 
structures and data type objects, 30 
in context of applications, 28 
displaying, 7 
Class diagram 

creating and modifying, 64-65 
sample, 64 

Class library, IBM Smalltalk, learning contents 
of, 71 

Class object, subclassing, 65-67 
Classes list in browser, 7 
CLDT subapplication, 29, 30-34 
object-management methods of, 66-67 
CldtConstants pool dictionary, 361 
CLIM subapplication, object-management 
methods of, 66 
Collection class 
as abstract class, 70 
defined by CLDT subapplication, 30-31 
in Prioritizer sample application, 43, 45 
Collection method, 131, 193 
Color 

in Busyness Indicator application, 347 
changed for bars of bar chart, 295 
changed for foreground of window, 267-68 
drawing in, 264-68 
Comma-delimited fields, 367-369 
Comments in method definition, 26 
Common File System, 34, 359-361 
Cfs prefix for class names of, 359 
CfsStreams subapplication of, 37 
constants and flags for file descriptors 
provided by, 369-70 
preparing to use, 361 
Common Graphics application, 35-36 
fonts in, 322-28 
graphics classes of, 252 
Common Process Model (CPM). See CPM 
subapplication 
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Common Widgets application, 36, 101-2 
core set of common resources for, 103 
object instance for, 252 
as a prerequisite, 117 
Context class in Core subapplication, 30 
Core subapplication, 30 
subapplication, object-management methods 
of, 66 

Counter sample project, 75-97 
adding components to, 87-91 
attaching branches for, 86 
creating application for, 78-81 
creating branches for, 84-85 
defining classes for, 78, 81-82 
defining window for, 83-84 
designing, 78 

initializing application for, 82 
overview of, 75 
saving Counter class for, 97 
user interface classes of, 76-77 
writing methods for, 92-97 
CPM subapplication, 29 
to arbitrate among processes and manage 
flow of processes, 34 

multiprocessing managed by classes in, 403-6 
Ctrl-Break 

to enter Debugger, 17 
to halt program execution, 14 
Counter sample project, 75-97 
CwBasicWidget class, 77 
CwComposite class, objects that can have zero 
or more children as subclasses of, 36, 77 
CwDialogShell class, one instance per applica¬ 
tion of, 101 

CwDrawingArea class 
application window for graphing as instance 
of, 272 

creating a GC object for, 283 
drawing bars in, 284 
method for widget of, 279-80 
scaling of data for, 282 
CwFileSelectionPrompter class 
in CwPrompters subapplication, 36 
in file input/output project to manage dialog, 
391-92 

interface to file searches provided by file 
searches, 375-76 
in Plot application, 300 
CwFontPrompter class 
font characteristics specified by, 355-57 
font prompter dialog supported by, 336 


CwForm class, 76 
as composite widget, 77 
as layout widget, 102 
CwList class to implement list boxes, 36 
CwMainWindow class, 76 
as always in content area of application 
window, 101 
as child widget, 77 

CwMessageBox class for user interactions, 46 
CwMessagePrompter class 
in CwPrompters subapplication, 37 
in Prioritizer project, 39, 46-47, 55-56 
CwPrimitive class, objects that cannot have 
children widgets as subclasses of, 36, 77 
CwPrompters subapplication, 37 
CwPushButton class to implement buttons and 
menus, 36, 87 

CwRowColumn class, 76, 122-24 
as composite widget, 77, 84 
as layout widget, 102 
menus as instances of, 111-12 
CwRowColumnExample class 
in Local Implementers list, 127 
modifications to, 128-30 
modular region methodology in, 147 
results of opening, 124 
running, 123 

CwShell class to contain and position other 
widgets, 36, 76-77 
CwText class 

to handle text objects, 36, 319 

menu options in, 281 

method for highlighting text using, 321 

methods for modifying text using, 320 

methods for scrolling text using, 320-21 

methods for selecting text using, 321 

modifying data in, 281 

Plot application window using, 272, 300-301 
special attributes of, 322 
CwTextPrompter class, 45 
in CwPrompters subapplication, 37 
in Prioritizer project, 39, 41-44 
user entry validation in Plot application 
using, 298 

CwTopLevelShell class, 76 
one instance per application of, 101 
as shell widget, 77 

CwWidget class, interactive application 
consisting of instances of, 76-77 
CwWMShell class, 76-77 
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Data transfers, encapsulation during, 176 
Date class, 115 

creating new instances of, 118-22 
defined by CLDT subapplication, 30, 33 
modifying method for, 168-69 
Debugger, 17-21 
actions taken in, 18 
editor in lower window of, 57 
error message display in, 49 
inspector opened from, 14-15 
on Prioritizer sample project, 54-57 
sample display of, 18 
three-step procedure for using, 21 
window displayed by, 19 
Delay class 

combined with a Semaphore class, 413-14 
defined by CPM application, 34 
Dependency in broadcasting messages, 177-78 
detect: method to search collection, 132 
Dictionary class, 43, 199 
creating new, 198 

defined by CLDT subapplication, 30-31 
Directories 

IBM Smalltalk’s handling of, 371-72 
searching, 373-75 
Directory path 
finding, 377 
parsing, 376 

“Do It” entries in Change Log Browser, 11 

E 

Edit menu 

opening an inspector using, 14 
saving application using, 53-54 
in Work space, 16 
Editing text, methods for, 320-21 
Encapsulation during data sharing, 176, 178-79 
Environment, IBM Smalltalk, 1-21 
graphic, 251-70 
holistic, 63 

major components of, 23 
overview of, 1-2 

EtBaseTools subapplication, object-manage¬ 
ment methods of, 66 

EtTranscript class in Prioritizer project, 48 
EtWorkspace class in Prioritizer project, 48 
Event framework, designing, 230 


Event handler method 
actions of, 238 
creating, 201 

Event management approach for multi-window 
applications, 175 
Event masks 

table of common widget, 111 
to tell application about types of events, 110 
Event notification, 176 
Events, 107-13 
high-level, 108-10 
low-level, 110-11 


False class defined by CLDT subapplication, 30 

Field delimiters, example of, 367-69 

File 

anatomy of, 360-61 
control characters in, 360 
File descriptors 
closing, 371 

file streams combined with, 371 
opening, 369-70 

File handling by IBM Smalltalk, 34 
File input/output sample project, 380-95 
appointments collection in, 388 
booking appointments in, 386-88 
building project for, 385-95 
designing project for, 381-85 
issues for, 382 

keeping appointments in, 383-85 
menus in, 393-95 

restoring appointments in, 385-86, 388-91 
storing and retrieving appointment data in, 
382,385 
testing, 395 

File mechanics, low-level, 369-75 
File menu 

saving Workspace using, 16 
Workspace created using, 16 
File streams, 361-69 
classes of, 362 
closing, 364 
examples of, 364-69 
file descriptors combined with, 371 
file descriptors used by, 371 
flushing, 364 
opening, 362-63 
processing, 363-64 
releasing resources of, 364 
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File systems, portability between platform- 
specific, 361 
Files 

management of external, 359-79 
opening and closing, 362-63 
Flat object storage, 377-78 
Float class defined by CLDT subapplication, 

30, 33 
Font(s) 

characteristics of single, 325 
Common Graphics subsystem classes for, 
322-28 

to create text, 328-34 

data structure for, 328 

default method for, 323, 324 

examples of using, 329-34 

interactions of classes of, 322-23 

maintaining information about, 323-24 

matching XLFD convention string to, 325-27 

name of, 325 

process of using, 329 

selecting, 355-57 

specified from a string name, 327 

unloading, 323, 324 

Fraction class defined by CLDT subapplication, 

31, 33 

ii 

Global variables, saving image after setting, 191 
Graphical user interface (GUI) of Smalltalk, 99, 
251-70 

Graphics concepts, 251-53 
Graphics Context (GC), 36 
Graphing application sample project, 271-318 
building application in incremental stages for, 
273-301 

callbacks in, 294, 295, 309 
code borrowed to create, 274, 276, 302 
colors of bars in, 295, 301 
CwDrawingArea widget of, 279-80, 290-91 
data retrieval and storage in, 299-301 
defining graph selection methods for, 286 
demonstrating, 288-89 
designing application for, 271-72 
display methods for, 310-11 
drawing bars in, 284-85 
enhancements to, 318 
events for, 302 

graph selection methods for, 286-88 


initialize method for, 283-84 
integrated with SimplePIM application, 271, 
301-18 

menus in, 272, 280, 281, 291-94, 299-300, 
311,313 

open method for, 274-76 

Plot Window of, 272 

plots arguments for, plotting, 282 

PlotWindow class of, 273, 281, 288, 302, 311 

sample graphs created by, 289 

selecting fill pattern in, 295 

setting up class files for, 273 

spacing and width of bars in, 296-97 

stream approach using carriage returns in, 303 

testing, 311-18 

text widget of, 275, 276-78 

user-selected graph arguments for, 290 

validation of user entries in, 296-98 

verticalBar method for, 285-86 

H 

Halt message, stopping program execution 
using, 14 

Highlighting text, methods for, 321 
Holidays 

Appointment Book application’s handling of, 
198-200 

Calendar application’s handling of, 138-39, 
144-45 

i 

IBM OS/2 as multithreaded environment, 34 
IBM Smalltalk environment of, 1-21, 63, 251-70 
IBM Smalltalk language, 23-38 
basic syntax of, 23 
as cross-platform language, 99 
message-passing syntax of, 24-25 
method-definition syntax of, 26-28 
Image menu, halting a method using, 247 
Indexed palette, 266 
Inspect message 
passing, 24 
sending, 14 

Inspector menu, opening an inspector using, 
14, 20 

Inspector window, 125 
title bar of, 21 
Inspectors, 14-15 
working with multiple, 244-45 
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Instance categories list in browser, 7 
Instance methods 
creating, 83-85 
event-related, 422-23 
examples of, 130 
listed in browser, 7 
time management, 423-25 
Instance Methods pop-up menu 
accessing template using, 53 
checking whether instances are public or 
private using, 126 

new method template accessed using, 92 
Instance variables to adding to class’ knowl¬ 
edge of itself, 65 

Integer class defined by CLDT subapplication, 
30, 33 

Inter-window communication, 175 

i 

Kernel application, 29 
automatic addition of, 117 
Keyword 

as any word of a message, 24 
ending with colon as having an argument, 
24-25 

requests by applications using, 226 

L 

Lazy initialization, 139 
Line feed (LF), 360 
Lines, drawing, 260-64 
Loaded Classes pop-up menu to show com¬ 
ments for class, 123 
“Local Implementers” list, 127 

M 

Magnitude class defined by CLDT 
subapplication, 31, 33 
Management of a widget, setting up, 102 
Menus 

attaching buttons to, 162-63 
hooking into chain of, 160-66 
in IBM Smalltalk, 112-13 
Message 

broadcasting, 177-79, 230 
execution of, 397-401 
method represented by, 399-400 
name of, 25 


sending, techniques for, 25 
sent to an instance, 122 
syntax for passing, 24-25 
tracing receiving class of, 18 
Message broadcasting technique, 175 
Message cascading, 25, 43 
Message passing, 397-98 
Metaclass class defined by Core subapplica¬ 
tion, 30 

Method List pop-up menu, viewing Object class 
outside of browser using, 81 
Method refactoring, 387 
Methods 

added to application, 72-73 
categories for subclassing of, 68-69, 72 
code segments that are candidates for 
becoming, 304 
comments in, 26, 28 
connecting buttons with, 93 
displaying source code for, 7-8 
do-nothing, purpose of, 70-71 
function, 104 

listing candidates for, 61-62 
lists of, 31 

represented by messages, 400 
resource, 103 
sample, 27-28 
statements portion of, 27 
syntax for defining, 26-28 
temporary or local variables enclosed in 
vertical bars (I) in, 27 
writing an application’s, 92-97 
Moderation, 175 

Multiple platforms, mixing double-byte and 
single-byte characters in, 368 
Multiprocessing, 397-417 
CPM subapplication classes to manage, 403-6 
examples of, 406-17 
non-preemptive, 402 
preemptive, 402 

Multiprocessing clock sample project, 419-53 
Clock class of, 419-20, 421-22, 426 
Clock object of, initializing, 428 
CIock2 class of, 450, 453 
ClockWindow class of, 419, 426, 428-46, 453 
day gear for, 452 
debugging, 428 

designing the application for, 419-20 
drive gear for, 450-51 
enhanced clock in, 449-53 
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event handling methods for, 433 
event-related instance methods for, 422-23 
hour gear for, 451 
menus in, 429, 435, 448 
minute gear for, 451 
remote control methods for, 435 
resetting the clock in, 436 
setting the next day in, 447-48 
storage and retrieval of appointments in, 
448-49 

storing and manipulating time in, 420-21 
testing, 447, 453 

time management instance methods for, 423-25 
toggle methods for, 436 
updating time in, 433-35 
utility methods of, 431-32, 452-53 
window control methods of, 430-31 
Mutex semaphores, 405-8 

s 

Number class defined by CLDT subapplication, 
30, 33 

o 

Object class 

classes created as subclasses of, 65 
defined by Kernel application, 29 
defining new object using, 146 
instance methods of, 65-67 
printstring method defined in, 50 
viewing, 80-81 

Object-oriented approach to project design, 40 
ways to store objects in external files as issue 
for, 382 

Object-oriented programming (OOP) 

’’feel” of, 59-60 

key difference between application develop¬ 
ment with traditional languages and, 63 
tight coupling viewed as weakness in, 179 
ObjectDumper class to dump objects into 
file, 378 

ObjectLoader class to retrieve objects from 
file, 378 
Objects 

assigning responsibilities to, 62-63 
collaboration of, 63 
creating, 65-68 


Date, 119-20 
defined, 14 
dependent, 222 
dependents of, 178-79 
displaying a string representation of them¬ 
selves, 50 
dumping, 377-78 

inspectors to examine or change contents of, 14 

listing candidates for, 61-62 

releasing, 107 

retrieved from files, 377-78 

storage of themselves handled by, 382-83 

stored in files, 378, 382 

text, 36, 320 

tracking messages through maze of, 60 
window, 254 
ObjectSwapper, 377-78 

“Onion,” peeling, object-oriented programming 
analogous to, 60 
open method 

of Appointment Book application, 204-6, 231 
of Calendar application, 146-56, 231 
callbacks assigned in, 93 
calls to other methods in, 155 
code for creating application’s widget tree in, 
89-91 

creating new instance method for, 83-85 
final form of Counter application’s, 94-96 
of Plot application, 274-76 
testing CalendarWindow application’s, 171 
OrderedCollection class defined by CLDT 
subapplication, 30-31, 32 
Ornaments. See Widgets 
OSF/Motif standard GUI design, 99-100 

p 

Palette 
default, 266 
defined, 266 
indexed, 266 
Parsing 

of directory path, 376 
process of, 359-60 
a string for a time, 185-86 
Performance problems, misuse of dependency 
and broadcast techniques as cause of, 178-79 
Persistent object storage, 377-78 
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Personal information manager (SimplePIM) 
application, 115 

alarming appointments in, 437-39 
flat storage of objects as part of, 378 
integrating graphing application into, 271, 
301-18 

inter-window communication in, 175-76 
loading, 273 
Piano keys, 4 
Pixel value, 266 
Pixels defined, 251 
Pixmap, 252, 255 

Platform dependencies, methods for dealing 
with, 372 
Point class 

creating new point using, 268 
defined by CLDT subapplication, 31, 33 
manipulating instances of, 269 
positions and areas represented by, 270 
Polygons, drawing filled, 263 
Pool dictionary, 81 
CfsConstants, 361 
CgConstants, 253 
CldtConstants , 361 
constants stored in, 104 
POSIX.l standard, 359-60 
Post-and-deferred method execution, 400 
Preferences Work space, 16-17 
Prerequisite applications 
defined, 80 
defining, 117 
nesting, 80 
Primitive objects, 382 
Prioritizer sample project, 39-57 
building, 40-44 

code for prioritize method of, 51 

creating home for prioritize method of, 52-54 

Debugger used on, 54-57 

designing, 40 

overview of, 39 

sorting the user’s list in, 45-50 
Process 

differences between a task and, 403 
forking, 449-50 

interrupting the receiver, 410-11 

priorities of, 401 

scheduling, 404 

states of, 400 

terminating, 19 

waiting time for, 401 


Process class 

defined by CPM subapplication, 34 
process functions managed by, 403 
Process Watcher process, 411 
engine for, 415-16 
modifying, 414-15 
Processes menu 

terminating use of Debugger using, 57 
tracing receiving class of message using, 18 
ProcessScheduler class 
defined by CPM subapplication, 34-35 
user interface events scheduled by, 404 
Program execution, halting, 14 
Programming techniques for IBM Smalltalk, 
59-74 

beginning programming tasks using, 61 
procedural approach in, 40 
Projects, sample 
appointment book, 181-249 
busyness indicator, 308, 335-58 
calendar, 115-74 
counter, 75-97 
file input/output, 381-95 
graphing, 271-318 
multiprocessing clock, 419-53 
personal information manager (SimplePIM), 
115, 174,179-80, 206, 302-18 
prioritizer, 39-57 

I! 

Read-only text mode, 322 
ReadStream class defined by CLDT 
subapplication, 31, 34 
ReadWriteStream class defined by CLDT 
subapplication, 31, 34 
Rectangle class 

defined by CLDT subapplication, 31, 33 
defining a rectangle using methods with, 
269-70 

positions and areas represented by, 270 
shrinking or expanding rectangle with method 
of, 270 

Rectangles, drawing, 262-63 
Report menu, creating fill-in-the-blanks form 
for IBM using, 19 

RowColumn widget, 123-24, 208-12 
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s 

Scrolling text, methods for, 320-21 
Selection of text, methods for, 321 
Selector as message sent, 24 
Semaphore class 
combining a Delay with, 413-14 
defined by CPM subapplication, 34-35 
IBM’s semaphore framework supported by, 
405-6 

as traffic signal, 408-9 
Semaphore signals, 450 
SequenceableCollection class, 45 
defined by CLDT subapplication, 30-31 
Set class, 43-44 

defined by CLDT subapplication, 30-31 
SimplePIM application. See Personal informa¬ 
tion manager (SimplePIM) application 
Smalltalk dictionary, classes and global vari¬ 
ables defined in, 224 
Smalltalk image, 10-12 
applications equipping, 28 
defined, 10 

removing classes from, 9-10 
saving, 9 

Smalltalk Tools menu 
adding application using, 79 
Application Manager window accessed using, 
52,118 

Change Log Browser activated using, 10 
choosing browser using, 6 
class browser invoked using, 13 
installing programming examples for, 123 
opening new browser using, 7 
reducing size of Change Log (compressing 
changes) using, 12 

Workspace of preference-setting code ac¬ 
cessed using, 16 

SMPLEPIM.APP application file, 183, 273 
SortedCollection class 
defined by CLDT subapplication, 32 
examined in browser, 49 
in Prioritizer project, 39, 40, 45-48 
Stack menu, copying text in stack trace using, 18 
Stack Trace 
copying text in, 18 
examining code in, 20 
Statement as a serial stream of messages, 
399-400 


Stream class defined by CLDT subapplication, 
30, 34 

String class defined by CLDT subapplication, 
30, 32 
Subclassing 

made accessible using methods, 68-69 
process of, 67-68 
Superclass (parent class), 65 
abstract, 430 

behavior embodied in method in, 69 
of Busyness Indicator appbcation, 336, 338-40 
modifications to integrated application’s, 
304-5 

Swapper application, 377-78 
Symbol class defined by CLDT subapplication, 
30, 32 

System Transcript 
sending message from, 25 
File menu in, 16 

T 

Tab-spacing size, 322 
Templates 
in the browser, 8-9 
for a new class definition, 67-68 
for a new method, 53 
Text manipulation, 319-34 
methods for, 320-22 
Threading, classes to support, 34 
Time class 

in Appointment Book sample project, 183-90 
defined by CLDT subapplication, 30, 33 
in file input/output project, 383-84 
in multiprocessing clock application, 421 
Time-slicing defined, 402 
“Trail End” list, 4 
filling, 127 

TrailBlazing Browser (TrailBlazer) 
advantage of, 6 
buttons of, 2-3 
customizing, 7 
features of, 4-6 

options for calendar application of, 116 
as universal browser, 3 

True class defined by CLDT subapplication, 31 
Type conversion, example of, 366-67 
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u 

UlProcess class, user interface processing 
handled by, 404 

“Uncategorized” method category, 72 
UndefinedObject class, method unconnected 
to a class as belonging to, 55 
User customization of IBM Smalltalk, 
problem of, 2 

i 

Values mask for graphics, 256-57 
Variables menu 
to remove entries, 244-45 
to see a list of keys, 244-45 

w 

Widget tree 

for Appointment Book application, 207-9, 221 
code in open method for creating, 89 
defining, 83 

realizing (displaying), 102 
shell and child widgets in, 77 
Widgets, 99-107 

aligned into rows and columns, 84-85 

attaching, 86-90 

basics of, 101-2 

child, 77, 132 

composite, 77, 101 

connected on four sides, 86 

controlling size of, 88 

defined, 36, 100 

defining sizes and relative positions of, 33 
as equivalent of subpanes, 100 
example of using, 104-7 
functions for, 104 
graphics, 336-37 

invisible until they are “realized,” 102 

label, 147-48, 181-82, 201-2 

list, 181-82, 15 

managed, 86, 102 

mapping, 103 

objects and memory automatically released 
for, 107 


primitive (ornaments), 77, 84, 87-91, 101 
resources associated with, 103-4 
shell, 77, 100, 231 

starting and stopping labeling of, 132 
text, 181-82, 214-15, 275, 277-79, 320-22, 
336, 338-40 
types of, 101 

unattached, misbehavior of, 88 
unmanaged, 102 

Wildcard characters $* and $? to search 
directories, 373 

Wilson, David A., class diagrams invented by, 64 
Windows 

application using multiple, 175-80. See also 
Appointment Book sample project 
building, 146-52 

changing foreground color of, 267-68 
communications among, 175-76 
do-nothing, creating, 106 
elements common to IBM Smalltalk, 2-3 
messages broadcast among, 177 
Word-wrapping supported by class CwText, 322 
Workspaces, 16-17 
creating new, 16 
saving, 16 

sending message from, 25 
WSP filename extension for, 16 
WriteStream class defined by CLDT 
subapplication, 31, 34 

x 

x and y instance variables for Point class, 268 
X Logical Font Description (XLFD) convention, 
325-27, 356 
X-Windows 

as client/server environment, 254 
graphical model used in IBM Smalltalk from, 
100,251-52 

x-y coordinate values, objects composed of, 33 
Xerox Palo Alto Research Center (PARC), 
Smalltalk created by, 99 
Xlib graphics library, 252 
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